Reference
Error codes
On this page
Every error Valet reports starts with a code, such as connector.boot_timeout. A code reads <entity>.<error>: the thing that failed, then what went wrong. A code never changes meaning.
You see codes in the CLI, the dashboard, MCP tool results, and your logs. Error pages show the code in parentheses, and HTTP error responses carry it in the X-Valet-Error-Code header. The message after the code says what happened, using the names you chose, and what to do.
People who can't change your agent, app, or site, such as visitors or someone messaging your agent, see a short sentence and the code instead. Each section below shows both. The samples use an org named acme, an agent named support-bot, an app named shop, and a site named report.
Accounts
account.not_logged_inNot logged in
The request didn't carry a Valet login.
Sample message
account.not_logged_in: You're not logged in to Valet. Log in, then try again.What to do: Log in (valet auth login in the CLI, or reconnect Valet in your MCP client), then try again.
account.login_expiredLogin expired
Your Valet login is too old and has expired.
Sample message
account.login_expired: Your Valet login expired. Log in again, then try again.What to do: Log in again (valet auth login in the CLI, or reconnect Valet in your MCP client).
account.suspendedAccount suspended or waitlisted
Valet suspended the account, or the account is on the waitlist.
Sample message
account.suspended: Your Valet account is suspended or on the waitlist. Email support@valet.dev if you think this is a mistake.What to do: Email support@valet.dev if you think a suspension is a mistake. A waitlisted account needs no action.
account.email_in_useEmail already in use
A sign-in brought an email that another Valet account already uses, under a different identity-provider account.
Sample message
account.email_in_use: Another account already uses jo@example.com. Contact your Valet administrator to sign in.What to do: Contact your Valet administrator, or email support@valet.dev.
Agents
agent.stoppedAgent stopped after repeated failures
The agent failed to start 5 times in a row, so Valet stopped trying. When Valet knows the last failure, the message leads with it and its own code.
Sample message
agent.stopped: support-bot stopped after 5 failed starts. See its logs for the last failure.What to do: Look up the leading code, or the last failure in the agent's logs. Fix it, then restart the agent (valet ps restart or restart_service).
agent.boot_timeoutAgent didn't start in time
The agent didn't finish starting within 3 minutes. The problem is on Valet's side.
Sample message
agent.boot_timeout: support-bot didn't finish starting within 3 minutes. This is on Valet's side.What to do: Restart the agent in a few minutes. If it keeps failing, email support@valet.dev.
agent.unresponsiveAgent stopped responding
The agent stopped answering for 90 seconds, so Valet replaced it. A tool or connector stuck on a long task is the usual cause.
Sample message
agent.unresponsive: support-bot stopped responding for 90 seconds after running for 2 hours, so Valet replaced it.What to do: Valet has already replaced the agent. If it repeats, look in its logs for a stuck tool.
agent.valet_errorAgent stopped by an error in Valet
A problem on Valet's side kept the agent from starting, or stopped it. Nothing in your setup caused it.
Sample message
agent.valet_error: support-bot couldn't start because of an error in Valet. This is on Valet's side.What to do: Restart the agent in a few minutes. If it keeps failing, email support@valet.dev.
agent.out_of_memoryAgent ran out of memory
The agent used more memory than it is allowed, so Valet stopped and restarted it. Tools or connectors that load whole files or large results at once are the usual cause.
Sample message
agent.out_of_memory: support-bot used more memory than it is allowed, so it was stopped and restarted. If this repeats, look for tools or connectors that load whole files or large results at once.What to do: Find the heavy tool in the agent's logs, then change the agent's instructions or detach the connector.
agent.exitedAgent exited
The agent stopped with an exit code, while starting or later. Its logs show the last error.
Sample message
agent.exited: support-bot exited with code 1 while starting.What to do: Read the agent's logs, fix the last error, then deploy again.
agent.tool_collisionTwo tools share a name
Two connectors, or a connector and a built-in tool, provide tools with the same name. An agent's tool names must be unique, so the agent can't start.
Sample message
agent.tool_collision: Linear and Granola both provide a tool named `create_issue`, and an agent's tool names must be unique. Detach one of them from support-bot.What to do: Detach one of the connectors from the agent.
agent.network_blockedAgent tried to reach a blocked host
The agent tried to reach a web address that Valet blocks for every agent. The message appears in the agent's logs.
Sample message
agent.network_blocked: The agent tried to reach api.example.com, which Valet's network policy blocks for all agents. Use a connector for this service.The agent sees
Network access to api.example.com is blocked by Valet's network policy. Don't retry. Tell the user you can't reach that site.What to do: Reach the service through a connector instead.
agent.not_deployedAgent has never been deployed
Someone opened the agent's address before the agent had a release, so there is nothing to show yet.
Visitors see
This agent isn't ready yet. Its owner hasn't deployed it. (agent.not_deployed)What to do: Deploy the agent, then open its address again.
Apps
app.exitedA process exited
A process exited with an error or was stopped by a signal. Valet starts it again, up to 5 times, and quotes its last output when it can.
Sample message
app.exited: shop's web exited with code 1. Its last output was "Error: Cannot find module 'express'". Valet is starting it again (attempt 3 of 5).What to do: Read the app's logs, fix the error, then deploy again.
app.port_not_boundThe web process didn't listen on $PORT
The web process must listen on 0.0.0.0 at the port in $PORT within 60 seconds of starting. It started slowly, used another port, or listened only on localhost.
Sample message
app.port_not_bound: shop's web didn't listen on $PORT (3000) within 60 seconds of starting. Its last output was "Compiling…". Listen on $PORT before slow startup work.What to do: Listen on 0.0.0.0:$PORT before slow startup work, and remove any PORT env var you set. Deploy again.
app.boot_timeoutThe app didn't start in time for a request
A request arrived while the web process was starting, and it wasn't ready in time.
Sample message
app.boot_timeout: shop's web wasn't ready for a request to GET /hello, so the visitor got an error page. If this keeps happening, see shop's logs.Visitors see
This app is starting. Try again in a minute. (app.boot_timeout)What to do: Try again in a minute. If it repeats, look in the app's logs for slow startup work.
app.startingA visitor got the starting page
A person opened the app while its web process was asleep. Valet started it and showed a page that reloads until the app is ready.
Sample message
app.starting: shop was starting, so a visitor's GET /hello got the starting page, which reloads until shop is ready.Visitors see
This app is starting. This page reloads when it's ready. (app.starting)What to do: Nothing to fix. If visitors see it often, look in the app's logs for slow startup work.
app.never_publishedThe app has no live release yet
Nothing serves the app's address because no deploy has finished.
Sample message
app.never_published: shop has no live release yet, so nothing serves its address. Deploy shop. If a deploy failed, its build says why.Visitors see
This app isn't published yet. (app.never_published)What to do: Deploy the app. If a deploy failed, read its build log.
app.no_web_processThe Procfile declares no web process
Only a process named web serves the app's address. The Procfile has other processes but none named web.
Sample message
app.no_web_process: shop's Procfile declares worker but no web, so shop's address serves nothing. Name the process that serves HTTP "web" and deploy again.Visitors see
This app isn't serving web pages. (app.no_web_process)What to do: Name the process that serves HTTP web in the Procfile, then deploy again.
app.scaled_to_zeroThe web process is scaled to zero
Someone scaled the web process to 0, which turns the app off.
Sample message
app.scaled_to_zero: shop's web is scaled to 0, so nothing serves its address. Scale web to 1 to turn shop on.Visitors see
This app is turned off. (app.scaled_to_zero)What to do: Scale web to 1 (valet ps scale web=1 or scale_service).
app.stoppedThe app stopped after repeated failed starts
A process failed to start 5 times in a row, so Valet stopped trying. When a request arrives, Valet tries once more and reports the last failure.
Sample message
app.stopped: shop's web stopped after 5 failed starts, and one more try for this request didn't start it in 75 seconds. Its last failure: shop's web exited with code 1 ("Error: Cannot find module 'express'"). Fix it and deploy again, or restart shop.Visitors see
This app isn't running right now. (app.stopped)What to do: Fix the last failure, then deploy again or restart the app.
app.request_timeoutThe app didn't respond in time
The web process didn't start its response within 60 seconds, so Valet stopped waiting and sent the visitor an error page.
Sample message
app.request_timeout: shop's web didn't start its response to GET /hello within 60 seconds, so Valet stopped waiting and sent the visitor an error page. Look in shop's logs for what /hello was doing; move slow work to a worker.Visitors see
This app took too long to respond. Try again. (app.request_timeout)What to do: Find the slow request in the app's logs and move its slow work to a worker.
app.connection_failedThe app refused or dropped the connection
Valet couldn't connect to the web process, usually because it was restarting or crashed while handling the request.
Sample message
app.connection_failed: Valet couldn't connect to shop's web for GET /hello. It may have been restarting or crashed; see shop's logs.Visitors see
This app isn't accepting connections right now. Try again. (app.connection_failed)What to do: Look in the app's logs for a crash or restart, then try again.
app.out_of_memoryA process ran out of memory
A process used more memory than it is allowed, so Valet stopped it and starts it again, up to 5 times.
Sample message
app.out_of_memory: shop's web used more memory than it is allowed and was stopped. Valet is starting it again (attempt 2 of 5). Reduce web's memory use.What to do: Reduce the process's memory use, then deploy again.
app.valet_errorA request failed on Valet's side
A problem on Valet's side stopped a request to the app. The app's code didn't cause it.
Sample message
app.valet_error: A problem on Valet's side stopped a request to shop (GET /hello). It isn't caused by shop's code. If it keeps happening, contact support@valet.dev.Visitors see
Something went wrong on Valet's side. Try again in a moment. (app.valet_error)What to do: Try again. If it keeps happening, email support@valet.dev.
app.token_name_takenApp already has a token with that name
A service token was minted with the name of one of the app's unrevoked tokens. A name is unique among an app's unrevoked tokens.
Sample message
app.token_name_taken: The billing app already has a token named ci. Revoke it first, or choose another name.What to do: Revoke the existing token first, or choose another name.
app.token_not_foundApp has no token with that name
A revoke named a service token the app doesn't hold, or one already revoked.
Sample message
app.token_not_found: The billing app has no token named nope. List the app's tokens to see their names.What to do: List the app's tokens to see their names, then revoke one by its name.
app.token_name_invalidToken name breaks the naming rule
A service token's name is 1 to 63 lowercase letters and digits, joined by single hyphens.
Sample message
app.token_name_invalid: The token name "CI_worker" isn't valid. Use 1 to 63 lowercase letters and digits, joined by single hyphens.What to do: Choose a name such as ci or nightly-sync.
app.token_expiry_invalidToken expiry isn't in the future
A service token's expiry couldn't be read as a time, or names a time that has already passed.
Sample message
app.token_expiry_invalid: The token's expiry isn't a time in the future. Give a later time, or no expiry for a token that never expires.What to do: Give a time in the future, or no expiry for a token that never expires.
app.token_limit_reachedApp holds its most tokens
An app holds at most a fixed number of unrevoked service tokens, 20 by default. Expired tokens count until they are revoked.
Sample message
app.token_limit_reached: The billing app has 20 tokens, the most an app can have. Revoke one first.What to do: Revoke a token the app no longer needs, then mint again.
Builds
build.failedA build step failed
A command in the build exited with an error, such as a missing package. The message names the step when Valet can tell, and the build log shows the error.
Sample message
build.failed: The build failed in `npm install`. Fix the error in the build log and deploy again. Nothing was deployed.If Valet can't tell which step failed
build.failed: The build failed. Fix the error in the build log and deploy again. Nothing was deployed.What to do: Fix the error in the build log (get_build over MCP), then deploy again.
build.unsupported_languageThe app's language isn't one Valet builds
Valet builds Node, Python, and Go apps. It found no file it recognizes at the app's root, so nothing installed the app's language and a process failed to start.
Sample message
build.unsupported_language: shop's web exited with code 127 ("bundle: command not found"). shop has a Gemfile, and Valet builds Node, Python and Go apps, so nothing installed Ruby. Valet looks for package.json, requirements.txt, pyproject.toml, Pipfile, setup.py, environment.yml or go.mod at the app's root.What to do: Put one of the listed files at the root of the folder you deploy, then deploy again.
build.timeoutThe build took too long
The build didn't finish within 15 minutes, so Valet stopped it. Nothing was deployed.
Sample message
build.timeout: The build didn't finish within 15 minutes, so Valet stopped it. Speed up the build, or move work that can wait to when web starts. Nothing was deployed.What to do: Speed up the build, or move work to when web starts, then deploy again.
build.out_of_memoryThe build ran out of memory
The build used more memory than a build gets, so Valet stopped it.
Sample message
build.out_of_memory: The build used more memory than a build gets, so it was stopped. Reduce what the build holds in memory. Nothing was deployed.What to do: Reduce what the build holds in memory, then deploy again.
build.too_largeThe built app is too large
The built app is over the 512 MB limit, compressed. Caches and data folders are common causes.
Sample message
build.too_large: The built app is over the 512 MB limit, compressed. Remove files the app doesn't need at run time. Nothing was deployed.What to do: Remove files the app doesn't need at run time, then deploy again.
build.valet_errorThe build failed on Valet's side
The build stopped because of a problem on Valet's side. Nothing was deployed, and the live release is unchanged.
Sample message
build.valet_error: The build stopped because of a problem on Valet's side. Nothing was deployed. Deploy again.What to do: Deploy again. If it keeps failing, email support@valet.dev.
build.supersededA newer deploy replaced the build
A newer deploy of the app replaced this build while it was still running, so Valet stopped it. Nothing was deployed from it. The newer deploy may already be live, or may still be building.
Sample message
build.superseded: A newer deploy replaced this build before it went live. Nothing was deployed from it.What to do: Nothing to fix. If the newer deploy left out a change this one had, deploy again.
Channels
channel.link_expiredTelegram link expired
Someone opened an agent's Telegram link more than 15 minutes after it was made, so the bot doesn't reply.
Sample message
channel.link_expired: A Telegram link was opened after it expired. Links work for 15 minutes.What to do: Make a new Telegram link and open it within 15 minutes.
channel.bad_signatureWebhook signature doesn't match
A webhook channel received a delivery signed with a different secret than the channel holds, so it refused the delivery.
Sample message
channel.bad_signature: orders-webhook rejected a delivery because its signature didn't match the channel's secret. Check that the sending service uses the same secret.The sending service gets
HTTP 401 {"error":"channel.bad_signature","message":"The signature didn't match the channel's secret."}What to do: Set the channel's secret in the sending service again.
channel.busyToo many messages waiting on one channel
An agent can have 50 messages waiting on one channel. When it is slow or stuck, Valet turns new messages away.
Sample message
channel.busy: The agent had 50 messages waiting from Slack, its limit, so Valet turned this one away. Check whether the agent is slow or stuck on a long task.Telegram senders see
I'm still working through earlier messages. Please send this again in a minute. (channel.busy)Chat page visitors see
This agent has too many messages waiting. Send yours again in a minute. (channel.busy)Webhook and email senders get
HTTP 429 {"error":"channel.busy","message":"The agent has too many messages waiting. Send this again in a minute."}What to do: Check the agent's logs and sessions for a stuck task, then send the message again in a minute.
channel.not_foundChannel not found
A command named a channel that the agent or org doesn't have.
Sample message
channel.not_found: support-bot has no channel named orders-webhook.What to do: Check the channel's name, then try again.
channel.name_takenChannel name already in use
A create or attach used a channel name that the agent or org already has.
Sample message
channel.name_taken: support-bot already has a channel named orders. Choose another name.If that channel is still being created
channel.name_taken: support-bot already has a channel named orders that is still being created. If that create stopped, Valet removes it within 5 minutes. Try again then.What to do: Choose another name.
channel.id_takenChannel ID already in use
A create repeated a channel ID with a different name, type, or settings. A retry with the same ID must send the same request.
Sample message
channel.id_taken: support-bot already has a channel created with this ID and different settings. Send the request again unchanged, or leave out the ID to create another channel.What to do: Send the request again unchanged, or leave out the ID to create another channel.
channel.type_takenAgent already has a channel of this type
An agent can have one Slack, Telegram, console, or MCP channel. A second one was refused.
Sample message
channel.type_taken: support-bot already has a Slack channel, support-slack. Remove it before adding another.For a type said with a leading vowel sound
channel.type_taken: support-bot already has an MCP channel, support-mcp. Remove it before adding another.If that channel is still being created
channel.type_taken: support-bot already has a Slack channel, support-slack, that is still being created. If that create stopped, Valet removes it within 1 minute. Try again then.What to do: Remove the existing channel before adding another.
channel.scope_not_allowedChannel type can't belong to an org or an app
An org-scoped or app create named a channel type that belongs to one agent. Apps take webhook, cron, and heartbeat channels.
Sample message
channel.scope_not_allowed: Telegram channels belong to one agent, so acme can't have one. Create it on an agent.Or
channel.scope_not_allowed: prodbot-webhook is an app, and slack channels belong to agents. Apps take webhook, cron, and heartbeat channels.What to do: Create the channel on an agent, or use one of the types an app takes.
channel.app_channels_disabledChannels on apps aren't available yet
A channel was created on an app in an organization that app channels aren't turned on for.
Sample message
channel.app_channels_disabled: Channels on apps aren't available for prodbot-webhook's organization yet.What to do: Try again once Valet turns app channels on for the organization.
channel.unknown_typeNo such channel type
A create named a channel type that Valet doesn't have.
Sample message
channel.unknown_type: Valet has no channel type called teams.What to do: Choose one of the listed channel types.
channel.already_attachedChannel already attached
An org channel was attached to an agent that already has it.
Sample message
channel.already_attached: orders-webhook is already attached to support-bot.What to do: No action is needed. The channel is attached.
channel.not_attachedNo attached channel with that name
A detach named an attached channel that the agent doesn't have.
Sample message
channel.not_attached: support-bot has no attached channel named orders.What to do: Check the channel's name, then try again.
channel.not_org_channelOnly org channels can be attached
An attach named a channel that belongs to one agent. Only org channels attach to other agents.
Sample message
channel.not_org_channel: orders-webhook belongs to support-bot, so it can't be attached to another agent. Only org channels can be attached.What to do: Create an org channel instead.
channel.mailbox_takenMailbox already bound to a channel
An email channel named a mailbox that another email channel already uses.
Sample message
channel.mailbox_taken: support@acme.valet.run is already bound to support-email. Choose another address, or remove support-email first.What to do: Choose another address, or remove the channel that holds it.
channel.trigger_takenTrigger already feeds a channel
A second channel was created for an account and trigger that already feed one.
Sample message
channel.trigger_taken: Linear's issue-created trigger already feeds linear-issues. Remove it first, or use that channel.What to do: Use the existing channel, or remove it first.
channel.secret_missingChannel signing secret isn't set
A delivery or schedule fire arrived, and the env var that holds the channel's signing secret is missing. The sender gets a 503.
Sample message
channel.secret_missing: orders-webhook couldn't check a delivery because its signing secret, env var ORDERS_WEBHOOK_SECRET, isn't set. Set it again, or recreate the channel.Or
channel.secret_missing: nightly-report couldn't check a delivery because its signing secret isn't stored as an env var. Recreate the channel.The sending service gets
HTTP 503 {"error":"channel.secret_missing","message":"The channel isn't ready to receive deliveries. Try again later."}What to do: Set the env var again, or recreate the channel.
channel.secret_name_takenSigning secret would overwrite an env var
A new channel's signing secret is stored in an env var named after the channel, and an env var with that name already exists.
Sample message
channel.secret_name_taken: orders-webhook can't be created because its signing secret would overwrite the env var ORDERS_WEBHOOK_SECRET. Rename the channel, or remove the env var.What to do: Rename the channel, or remove the env var.
channel.path_requiredApp channel needs a path
A channel on an app was created without the path where the app handles each delivery.
Sample message
channel.path_required: A channel on prodbot-webhook needs a path, such as /webhooks/stripe, where the app handles each delivery.What to do: Pass path, such as /webhooks/stripe.
channel.path_invalidChannel path is malformed or reserved
A channel's delivery path must start with /, stay out of the reserved /__valet prefix, fit in 512 bytes, carry no query or fragment, no %, no . or .. segment, and no spaces or control characters.
Sample message
channel.path_invalid: /__valet/hook is reserved for Valet. Choose a path your app handles, such as /webhooks/stripe.Or
channel.path_invalid: webhooks/stripe isn't a path: it must start with /. Choose a path your app handles, such as /webhooks/stripe.What to do: Choose a path your app handles, such as /webhooks/stripe.
channel.verify_requiredApp channel must verify its sender
A webhook channel on an app was created without a signing scheme, so Valet can't tell the sender from anyone else.
Sample message
channel.verify_required: stripe can't skip verification because it delivers to an app. Use a signing scheme, or static-token if the sender can't sign.What to do: Use a signing scheme, or static-token if the sender can't sign.
channel.delivery_failedDeliveries to an app keep failing
Five failed delivery attempts in a row, or one delivery used up its retries. The app answered with an error or a 404, or didn't answer.
Sample message
channel.delivery_failed: The last 5 delivery attempts to POST /webhooks/stripe on prodbot-webhook returned 404. Check that the app handles that path, or change the channel's path.What to do: Check that the app handles the channel's path, or change the path.
channel.valet_errorValet couldn't create or change a channel
Valet's own create or update path failed, including a create that was abandoned partway.
Sample message
channel.valet_error: Valet couldn't create orders-webhook because of a problem on Valet's side. Nothing was created. Try again.If updating a channel fails
channel.valet_error: Valet couldn't update orders-webhook because of a problem on Valet's side. Try again.What to do: Try again. If it keeps happening, email support@valet.dev.
Chat
chat.rate_limitedToo many chat messages in a short time
A visitor sent chat messages faster than the agent accepts, so Valet turned this one away.
Visitors see
You're sending messages faster than this agent accepts. Try again in a few minutes. (chat.rate_limited)What to do: Wait a few minutes, then send the message again.
chat.session_not_foundChat session not found
The conversation doesn't exist, or the person asking for it isn't the one who started it.
Visitors see
This conversation doesn't exist or isn't yours. (chat.session_not_found)What to do: Start a new chat.
CLI
cli.upgrade_requiredThe Valet CLI is too old to deploy
Valet CLI versions before 0.1.89 upload source in a way Valet no longer accepts. Nothing was deployed.
Sample message
cli.upgrade_required: This version of the Valet CLI can no longer deploy support-bot. Nothing was deployed; the current release is still live. Update the CLI with `valet update`, then run the command again.What to do: Update the CLI with valet update, then run the command again.
Connector setup
connector_setup.not_foundConnector setup not found
The setup is unavailable to the current person in this organization.
Sample message
connector_setup.not_found: Connector setup not found.What to do: Check the organization and sign in as the person who started the setup.
connector_setup.expiredConnector setup expired
The request key is outside the setup retry period.
Sample message
connector_setup.expired: This connector setup expired. Start a new setup.What to do: Check existing connectors, then start a new setup if needed.
connector_setup.mismatchConnector setup changed
The request does not match the saved setup or its current state.
Sample message
connector_setup.mismatch: This connector setup no longer matches the request. Start a new setup.What to do: Check existing connectors, then start a new setup if needed.
Connectors
connector.revokedConnector authorization revoked
The provider stopped accepting the authorization Valet holds for a connector. The grant was revoked or expired, or the provider refused it even after Valet renewed it.
Sample message
connector.revoked: Linear stopped accepting support-bot's authorization. Reconnect Linear.What to do: Reconnect the connector (Reauthorize in the dashboard, valet connectors reauthorize <name>, or reauthorize_connector), then restart the agent.
connector.boot_timeoutConnector didn't respond at startup
A connector didn't answer within 60 seconds of the agent starting. Its server was slow or down, or its URL points at a server that never answers.
Sample message
connector.boot_timeout: Granola (mcp.granola.ai) didn't respond within 60 seconds of support-bot starting. Slack connected. Granola may be having an outage. If this keeps happening, detach Granola from support-bot.What to do: Restart the agent in a few minutes. If it keeps happening, detach the connector.
connector.env_var_missingConnector env var not set
The connector reads its key from an env var that neither the org nor the agent has set, or the name has a typo.
Sample message
connector.env_var_missing: The Linear connector reads its key from LINEAR_API_KEY, and no env var with that name is set. Set it, then try again.What to do: Set the env var (valet env set NAME=value or set_env_vars), then restart the agent.
connector.key_rejectedConnector rejected its API key
The provider refused the connector's API key, at startup or during a tool call. The key was revoked, rotated, or mistyped, or it belongs to another account.
Sample message
connector.key_rejected: Granola rejected the API key saved in Granola's connector settings (Granola says: "Invalid API key"). support-bot can't start until you update the API key in Granola's connector settings.If the key is in an env var
connector.key_rejected: Granola rejected the API key in GRANOLA_API_KEY (Granola says: "Key revoked"). support-bot can't start until you update that env var.What to do: Update the key where the message says, in the connector's settings or in the env var, then restart the agent.
connector.unreachableConnector server unreachable
Valet couldn't reach the connector's server, or the server returned an error. The address may be wrong, or the provider may be down.
Sample message
connector.unreachable: Valet couldn't reach Linear at mcp.linear.app: the address didn't resolve. Check the connector's URL. If it's right, Linear may be down.What to do: Check the connector's URL. If it's right, wait for the provider to recover, then restart the agent.
connector.private_addressConnector URL resolves to a private address
This installation lets connectors reach only public addresses. The connector's URL resolves to an address on a private network, either when you connected it or when an agent called one of its tools.
Sample message
connector.private_address: Valet couldn't connect to Wiki at wiki.corp.example.com: the address is on a private network, and connectors here can reach only public addresses. Use a public URL for this connector.If Valet has no name or host to show
connector.private_address: Valet couldn't connect to the connector: the address is on a private network, and connectors here can reach only public addresses. Use a public URL for this connector.What to do: Use a public URL for the connector. A name that resolves to a private address is refused even when it looks public.
connector.command_failedConnector command failed
A connector that runs a command failed while the agent was starting. The message says how: the package couldn't be installed, the command wasn't found, or the process exited.
Sample message
connector.command_failed: Granola's command `npx @acme/granola-mcp` failed while support-bot was starting: the package couldn't be installed. Check the package name and version in Granola's connector settings.What to do: Fix the command, package, or version in the connector's settings, then restart the agent.
connector.command_not_allowedConnector command not allowed
Agents can run a fixed set of commands, such as npx and uvx. The connector's command isn't one of them.
Sample message
connector.command_not_allowed: Granola runs `bunx`, which agents can't run. Agents can run commands such as `npx` and `uvx`. Change Granola's command, or use its hosted URL.What to do: Change the connector's command to one agents can run, or use the provider's hosted URL.
connector.valet_errorValet couldn't connect the agent to a connector
A problem on Valet's side kept the agent from using a connector. Nothing in your setup caused it.
Sample message
connector.valet_error: Valet couldn't connect support-bot to Linear. This is on Valet's side.What to do: Restart the agent in a few minutes. If it keeps failing, email support@valet.dev.
connector.auth_declinedAccess declined on the consent screen
Someone chose Cancel or Deny on the provider's consent screen, so the connector wasn't connected. The message shows on the page the browser lands on.
Sample message
connector.auth_declined: Linear wasn't connected because access was declined on Linear's consent screen. Connect Linear again when you're ready.What to do: Connect again and choose Allow on the consent screen.
connector.auth_link_expiredAuthorization link expired
A link to connect a connector works for 15 minutes. This one was opened later.
Sample message
connector.auth_link_expired: This link to connect Linear expired. Links work for 15 minutes. Connect Linear again to get a new one.What to do: Connect again to get a new link.
connector.auth_failedProvider refused to finish the authorization
The provider refused to connect after the consent screen. The message quotes the provider when it gave a reason. When your org uses its own OAuth app, a wrong client secret or a missing redirect address is the usual cause.
Sample message
connector.auth_failed: Linear refused to connect (Linear says: "invalid_grant"). Try connecting again.If your org uses its own OAuth app
connector.auth_failed: Linear refused your organization's OAuth app (Linear says: "Client authentication failed."). Check its client secret and that it allows the redirect address https://api.valet.dev/oauth/connector/callback, then connect Linear again.What to do: Connect again from one browser tab. If the message names your org's OAuth app, fix it first.
connector.setup_expiredUnfinished connector removed
Valet removes a connector that isn't authorized within an hour of being added. The link was for a connector that's gone.
Sample message
connector.setup_expired: linear was removed before you finished connecting it. Add it again.What to do: Add the connector again and finish connecting it within the hour.
connector.org_client_requiredProvider needs your org's own OAuth app
Some providers only connect through an OAuth app that your org registers with them, and Valet has none on file for your org.
Sample message
connector.org_client_required: Linear only connects through an OAuth app that your organization registers with Linear. Register one, then email its client ID and secret to support@valet.dev, and Valet will set it up.What to do: Register an OAuth app with the provider, then email its client ID and secret to support@valet.dev.
connector.auth_link_invalidAuthorization link damaged or already used
The link was opened twice, cut short when it was copied, or is out of date. If you just connected, it worked.
Sample message
connector.auth_link_invalid: This link to connect Linear is damaged, out of date, or already used. If you just connected Linear, you can close this page. Otherwise connect Linear again to get a new link.What to do: If you just connected, close the page. Otherwise connect again for a new link.
connector.auth_admin_blockedWorkspace admin blocks Valet
Your Google Workspace admin hasn't allowed Valet to connect, so Google refused.
Sample message
connector.auth_admin_blocked: Google refused to connect Google Drive because your organization's Google Workspace admin hasn't allowed Valet. Ask them to allow it, then connect Google Drive again.What to do: Ask the admin to allow Valet, then connect again.
Conversations
conversation.too_longConversation too long for the model
A conversation reached the model's size limit and can't continue. Large tool results are the usual cause.
Sample message
conversation.too_long: A conversation with support-bot reached the model's limit and can't continue. Large tool results are the usual cause.MCP callers see
Sorry, the agent couldn't answer this message. Please try again later.What to do: Start a new conversation, or a new thread in Slack.
Dashboard
Deploys
deploy.needs_setupDeploy needs connectors, channels, or skills first
The agent's valet.yaml names connectors, channels, or skills that your org hasn't set up yet.
Sample message
deploy.needs_setup: support-bot's valet.yaml needs the linear connector, the skill pdf-tools set up first. Nothing was deployed. You can also deploy anyway, and support-bot runs without the missing pieces until you add them.What to do: Set up the missing pieces, or deploy anyway and add them later (valet deploy --allow-unsatisfied).
deploy.draft_openAnother deploy is in progress
The agent or app has changes open from another deploy that hasn't finished: someone else's, or an earlier one of yours.
Sample message
deploy.draft_open: support-bot has changes open from another deploy that hasn't finished. Deploying now would replace them. Discard them, or deploy again and choose to replace them.What to do: Check with whoever started it, then discard the open changes: publish again with discard_draft: true over MCP, or find the draft with valet drafts and run valet drafts discard <id>.
deploy.activation_failedNew release saved but not live
Valet saved the new release but couldn't start it. The problem is on Valet's side, and the previous release, if any, is still live.
Sample message
deploy.activation_failed: Valet saved support-bot's changes but couldn't start them. The current release is still live. This is on Valet's side, not yours. Deploy again to retry.What to do: Deploy again. If it keeps failing, email support@valet.dev.
deploy.source_movedThe service changed during the deploy
A person, or the agent itself, changed the service or skill while you were deploying or publishing it, or since you read the skill. Nothing was deployed or published.
Sample message
deploy.source_moved: support-bot changed while you were deploying. Nothing was deployed; the current release is still live. Your changes are kept. Deploy again.Publishing a skill's files
deploy.source_moved: research changed while you were publishing. Nothing was published; v5 is now the latest. Publish again.Publishing a skill's push
deploy.source_moved: research changed while you were deploying. Nothing was deployed; the current release is still live. Your changes are kept. Deploy again.Saving a skill's edited files
deploy.source_moved: research changed since you opened it. Nothing was published; v5 is now the latest. Reload it and make your edit again.What to do: Deploy again. For a skill, read its latest version, make your change again, and publish it.
deploy.push_expiredThe push is no longer open
The push passed its expiry, or a publish already used it. Nothing was deployed, and the current release, if any, is still live.
Sample message
deploy.push_expired: The push for docs-site is no longer open: it expired, or it was already published. Nothing was deployed; the current release is still live. If your change isn't live, create a new push and push again.What to do: Check whether your change is live. If it isn't, create a new push and push again.
deploy.push_mismatchThe push holds a different commit
The commit you named isn't the one you pushed. Nothing was deployed.
Sample message
deploy.push_mismatch: The push for docs-site holds commit 4be2a91, not 9c01f3e. Nothing was deployed. Push again, then publish the commit you pushed.Publishing a skill's push
deploy.push_mismatch: The push for research holds commit 4be2a91, not 9c01f3e. Nothing was deployed. Push again, then publish the commit you pushed.What to do: Push again, then publish the commit you pushed.
deploy.too_many_pushesThe service has too many open pushes
The service holds the most open pushes it can. Each expires on its own schedule.
Sample message
deploy.too_many_pushes: docs-site has 10 open pushes, the most it can hold. The oldest expires at 14:05 UTC. Publish an open push or wait, then create a push.Publishing a skill's push
deploy.too_many_pushes: research has 10 open pushes, the most it can hold. The oldest expires at 14:05 UTC. Publish an open push or wait, then create a push.What to do: Publish an open push or wait for the oldest to expire, then create a push.
deploy.source_invalidThe pushed source has an entry Valet can't deploy
The pushed source or published files hold an entry other than a regular file, such as a symbolic link or a Git LFS pointer. Nothing was deployed or published.
Sample message
deploy.source_invalid: docs-site's pushed source has a symbolic link at assets/logo.svg. Valet deploys regular files only. Nothing was deployed. Replace the link with the file and push again.Or
deploy.source_invalid: docs-site's pushed source has a submodule at vendor/lib. Valet deploys regular files only. Nothing was deployed. Replace the submodule with its files and push again.Or
deploy.source_invalid: docs-site's pushed source has a reserved .git path at assets/.git/config. Valet deploys regular files only. Nothing was deployed. Remove the .git path and push again.Or
deploy.source_invalid: docs-site's pushed source has a Git LFS pointer at assets/hero.png. Valet deploys regular files only. Nothing was deployed. Push the file's contents instead of its Git LFS pointer, and push again.Or
deploy.source_invalid: docs-site's pushed source has a device entry at dev/null. Valet deploys regular files only. Nothing was deployed. Remove the entry and push again.Publishing a skill's files
deploy.source_invalid: research's files have a reserved .git path at .git/config. Valet publishes regular files only. Nothing was published; v3 is still the latest. Remove the .git path and publish again.Publishing a skill's files
deploy.source_invalid: research's files have a Git LFS pointer at assets/hero.png. Valet publishes regular files only. Nothing was published; v3 is still the latest. Publish the file's contents instead of its Git LFS pointer.Publishing a skill's push
deploy.source_invalid: research's pushed source has a symbolic link at scripts/run.sh. Valet deploys regular files only. Nothing was deployed. Replace the link with the file and push again.Saving a skill's edited files
deploy.source_invalid: research's edit of assets/logo.png isn't text, and Valet edits text files only. Nothing was published; v3 is still the latest. Leave the file out of your edit and publish again.What to do: Replace the entry with a regular file, then push or publish again. For a Git LFS pointer, send the file's contents.
deploy.too_largeThe pushed source is over a deploy limit
The pushed source or published files hold more files, or more bytes in one file or in total, than a service or skill allows. Nothing was deployed or published.
Sample message
deploy.too_large: docs-site's pushed file assets/video.mp4 is 26 MB, and a file can be at most 25 MB. Nothing was deployed. Shrink or remove the file and push again.Or
deploy.too_large: docs-site's pushed source is 61 MB, and a site can be at most 50 MB. Nothing was deployed. Remove files and push again.Or
deploy.too_large: docs-site's pushed source has 612 files, and a site can hold at most 500. Nothing was deployed. Remove files and push again.Or
deploy.too_large: web-app's Procfile is over 1 MB, the most Valet reads from it. Nothing was deployed. Shrink the file and deploy again.Publishing a skill's files
deploy.too_large: research's file assets/video.mp4 is 26 MB, and a file can be at most 25 MB. Nothing was published; v3 is still the latest. Shrink or remove the file and publish again.Publishing a skill's files
deploy.too_large: research has 612 files, and a skill can hold at most 500. Nothing was published; v3 is still the latest. Remove files and publish again.Publishing a skill's files
deploy.too_large: research's files are 61 MB, and a skill can be at most 50 MB. Nothing was published; v3 is still the latest. Remove files and publish again.Publishing a skill's push
deploy.too_large: research's pushed source is 61 MB, and a skill can be at most 50 MB. Nothing was deployed. Remove files and push again.Publishing a skill's push
deploy.too_large: research's pushed source has 612 files, and a skill can hold at most 500. Nothing was deployed. Remove files and push again.Publishing a skill's push
deploy.too_large: research's pushed file assets/video.mp4 is 26 MB, and a file can be at most 25 MB. Nothing was deployed. Shrink or remove the file and push again.What to do: Remove or shrink files, then push or publish again.
deploy.procfile_missingThe app has no Procfile
An app needs a Procfile at its root that declares a web process. Nothing was deployed.
Sample message
deploy.procfile_missing: web-app has no Procfile. An app needs a Procfile at its root that declares a web process. Nothing was deployed. Add a Procfile and deploy again.What to do: Add a Procfile and deploy again.
deploy.procfile_invalidThe app's Procfile has a line Valet can't read
Each Procfile line reads type: command. The message names the line at fault. Nothing was deployed.
Sample message
deploy.procfile_invalid: web-app's Procfile has a line Valet can't read, "web node server.js": expected "type: command". Nothing was deployed. Fix the line and deploy again.What to do: Fix the line and deploy again.
deploy.checkingThe release waits for the organization's release policies
The organization's policies evaluate every release before it goes live. Your new release is built and waits for its evaluation, or you changed a service that already has a waiting release. Nothing new is live.
Sample message
deploy.checking: support-bot's changes are waiting for acme's release policies. Nothing new is live; the current release still is. Wait for the evaluation to finish, or publish again to replace the waiting release.Or
deploy.checking: support-bot's changes are waiting for acme's release policies. Nothing new is live; the current release still is. They go live once the policies pass.What to do: If your release waits, it goes live once the policies pass. If another release waits, wait for the evaluation to finish, or publish again to replace the waiting release.
deploy.draft_uncheckedA draft can't reach main before it is evaluated
The organization's policies evaluate every release, and publishing a draft moves main before it builds. Nothing was deployed.
Sample message
deploy.draft_unchecked: acme's policies evaluate every release, so support-site's draft can't move to main before it's built and evaluated. Deploy it instead.What to do: Deploy the draft instead.
deploy.policy_blockedA release policy blocked the release
A blocking policy found something at or above its severity. Nothing was deployed, and the current release is still live.
Sample message
deploy.policy_blocked: acme's policies blocked support-bot's changes: secrets found 1 finding at high or above. Nothing was deployed; the current release is still live. Fix it and deploy again.What to do: Fix the blocking findings at their origin, then deploy again. valet policies show lists them.
deploy.policy_erroredA release policy couldn't evaluate the release
A blocking policy errored or timed out, so Valet can't tell whether the release is safe. Nothing was deployed, and the current release is still live.
Sample message
deploy.policy_errored: acme's policy "snyk-deps" couldn't evaluate support-bot's changes (it says: "Snyk returned 401"). Nothing was deployed; the current release is still live. Deploy again. If this keeps happening, change or remove the policy.What to do: Deploy again. If it keeps failing, change or remove the policy.
deploy.supersededA newer publish replaced a waiting release
You published again while an earlier release waited for the organization's release policies. Valet refused the waiting release and canceled its evaluation. Nothing from it was deployed.
Sample message
deploy.superseded: A newer publish of support-bot replaced this release while it waited for acme's release policies. Nothing from it was deployed.What to do: Follow the newer publish.
Log drains
drain.invalid_endpointDrain endpoint isn't an https URL
A drain needs at least one endpoint, for logs, traces, or metrics, and each must be an https URL with a host. Drain headers often carry the receiver's credentials, so Valet never sends them in the clear. A drain's endpoints can be at most 2,048 bytes together.
Sample message
drain.invalid_endpoint: "http://otlp.example.com/v1/logs" isn't an https URL. A drain's headers often carry credentials, so Valet sends telemetry only over https. Use an https endpoint, and give the drain at least one.If the request names no endpoint
drain.invalid_endpoint: A drain needs at least one endpoint. Give it an https URL for logs, traces, or metrics.If the endpoints are too long
drain.invalid_endpoint: A drain's endpoints can be at most 2,048 bytes together. Use shorter URLs.What to do: Create the drain again with at least one https endpoint, using URLs short enough to fit.
drain.existsDrain already exists for the endpoint
The service, or the org for an org drain, already sends its telemetry to these endpoints.
Sample message
drain.exists: support-bot already has a drain for https://otlp.example.com/v1/logs. To change its headers, destroy that drain and create it again.For an org drain
drain.exists: acme already has a drain for https://otlp.example.com/v1/logs. To change its headers, destroy that drain and create it again.If the request changes a drain's endpoints
drain.exists: acme already has another drain for https://otlp.example.com/v1/logs. Use different endpoints, or remove that drain first.What to do: Change the existing drain instead, or destroy it and create it again.
drain.id_takenDrain ID already used
The request named a drain ID that another drain has used, including a drain that was destroyed. A drain ID is never reused.
Sample message
drain.id_taken: Another drain has already used the ID in this request. Leave out the ID, or send a new one.What to do: Leave out the ID, or send a new one.
drain.not_foundNo such drain
The agent, app, or org has no drain for the endpoint or ID the request named.
Sample message
drain.not_found: support-bot has no drain for https://otlp.example.com/v1/logs. List its drains to check the endpoint.If the request names a drain ID
drain.not_found: support-bot has no drain with the ID in this request. List its drains to check the ID.What to do: List the drains with valet drains, and check the endpoint.
drain.org_managedDrain belongs to the org
The drain is an org drain. It receives telemetry from every service in the org, so it can't be changed or removed from one service.
Sample message
drain.org_managed: This drain applies to every service in acme. Only an org Admin can remove it.If the request changes the drain
drain.org_managed: This drain applies to every service in acme. Only an org Admin can change it.What to do: Ask an org Admin to change or destroy it from the org.
drain.name_takenDrain name already used
Another drain on the service, or another org drain, already has this name. Names are compared without regard to case.
Sample message
drain.name_taken: acme already has a drain named Honeycomb. Choose another name.What to do: Choose another name.
drain.invalid_nameDrain name isn't valid
A drain's name needs 1 to 64 characters, with no line breaks or other control characters.
Sample message
drain.invalid_name: A drain's name needs 1 to 64 characters, with no line breaks or other control characters.What to do: Choose a name that fits.
Logs
logs.follow_limitToo many live log views are open
The same logs already have 64 live views open, so another view can't follow them.
Sample message
logs.follow_limit: Too many live log views are open for these logs (limit 64). Close another live log view and try again.What to do: Close another live log view and try again.
logs.follow_interruptedLive logs ended before all records could be shown
New records arrived faster than this live view could show them, so the view stopped.
Sample message
logs.follow_interrupted: Live logs stopped before all new records could be shown. Open a new log view to load recent logs and continue.What to do: Open a new log view to load recent logs and continue.
logs.valet_errorValet couldn't load logs
A problem on Valet's side prevented the logs from loading. Nothing in your setup caused it.
Sample message
logs.valet_error: Valet couldn't load these logs because of a problem on Valet's side. Try again later.What to do: Try again later.
Manifests
manifest.invalidvalet.yaml isn't valid
A field in valet.yaml is missing or wrong, or the file doesn't parse. The message lists each problem with its line.
Sample message
manifest.invalid: valet.yaml has 3 problems:
- line 1: display_name is required
- line 1: category is required
- line 5: channels[1]: every is required for heartbeat channelsWhat to do: Fix each listed line, then deploy again. valet manifests validate checks the file first.
manifest.soul_missingAgent has no SOUL.md
An agent needs a SOUL.md at its root that says who it is.
Sample message
manifest.soul_missing: support-bot has no SOUL.md. An agent needs a SOUL.md at its root that says who it is. Nothing was deployed.What to do: Add a SOUL.md at the agent's root, then deploy again.
Messages
message.model_overloadedReply delayed by a temporary problem on Valet's side
The agent couldn't reply because of a temporary problem on Valet's side. Valet tries again by itself.
Sample message
message.model_overloaded: support-bot couldn't reply because of a temporary problem on Valet's side. Valet will try again.MCP callers see
Sorry, the agent couldn't answer this message. Please try again later.What to do: No action is needed. If it keeps happening, email support@valet.dev.
message.usage_limitReply blocked by a problem on Valet's side
The agent couldn't reply because of a problem on Valet's side. Nothing in your setup caused it.
Sample message
message.usage_limit: support-bot couldn't reply because of a problem on Valet's side. Try again later.MCP callers see
Sorry, the agent couldn't answer this message. Please try again later.What to do: Send the message again later. If it keeps happening, email support@valet.dev.
message.reply_cut_offReply cut off at the model's output limit
The model hit its output limit partway through a reply, usually while writing a large file in one step.
Sample message
message.reply_cut_off: support-bot's reply was cut off: the model hit its output limit partway through a Write call of 2.1 MB. Ask support-bot to write large files in smaller pieces.MCP callers see
Sorry, the agent couldn't answer this message. Please try again later.What to do: Ask the agent to write large files in smaller pieces.
message.delivery_failedReply written but couldn't be posted
The agent wrote a reply, but Slack or Telegram refused to post it. The message quotes the channel's reason.
Sample message
message.delivery_failed: Slack refused the agent's reply in channel C07ABC123 because the bot can't post there (Slack says: "not_in_channel"). Check that the bot is in the channel and allowed to post, or detach the channel from the agent.If the Slack app lost access
message.delivery_failed: Slack refused the agent's reply because the workspace no longer authorizes the Slack app (Slack says: "token_revoked"). Reconnect the Slack channel.People in the chat see
Sorry, I wrote a reply but couldn't post it here. (message.delivery_failed)What to do: Add the bot to the channel, or reconnect the channel. A Telegram user who blocked the bot needs nothing from you.
message.expiredMessage waited an hour without being picked up
The agent didn't pick up a message within an hour, usually because it was stopped or busy, so Valet dropped it.
Sample message
message.expired: A message from Slack waited too long for the agent to pick it up, so Valet dropped it.MCP callers see
Sorry, the agent couldn't answer this message. Please try again later.What to do: Check that the agent is running, then send the message again.
message.agent_not_deployedMessage for an agent with no release
A channel delivered a message to an agent that has never been deployed.
Sample message
message.agent_not_deployed: The agent received a message from Telegram, but it has no release. Deploy the agent, or detach the channel.MCP callers see
Sorry, the agent couldn't answer this message. Please try again later.What to do: Deploy the agent, or detach the channel.
Names
name.takenName already in use
Agents, apps, sites, and skills in an org share one set of names, and something already uses this one.
Sample message
name.taken: acme already has an agent, app, site, or skill named report. Choose another name.If your agent was never deployed
name.taken: acme already has an agent named support-bot, created earlier but never deployed. Deploy it instead of creating it again.What to do: Choose another name. If the message says the agent was never deployed, deploy it instead.
name.invalidName not allowed
Names are 3 to 63 lowercase letters, digits, and hyphens, and start and end with a letter or digit. Skill names also require single hyphens.
Sample message
name.invalid: "-bad-" can't be a name. Names are 3 to 63 lowercase letters, digits, and hyphens, and start and end with a letter or digit.For a skill name
name.invalid: "qa" can't be a skill name. Skill names are 3 to 63 lowercase letters, digits, and single hyphens, and start and end with a letter or digit.What to do: Choose a name that follows those rules.
name.retiredName used before and never reused
The org used this name before. Valet never reuses an address, so old links can't reach something new.
Sample message
name.retired: "report" was used in acme before, and Valet never reuses an address, so old links can't reach something new. Choose another name.What to do: Choose another name.
name.reservedName reserved by Valet
Valet keeps some names for itself, such as the name of each org's Architect agent, the name of each built-in skill for agents, apps, and sites, and some names that mail and web clients treat as special.
Sample message
name.reserved: "architect" is reserved. Choose another name.If the name belongs to a built-in skill
name.reserved: "security" is the name of a built-in skill. Create a skill named security to customize it, or choose another name.If the skill customizes a built-in skill
name.reserved: security customizes Valet's built-in skill of that name, so it can't be renamed. To keep this version under another name, create a skill with that name. Nothing was renamed.What to do: Choose another name.
Organizations
org.billing_requiredPayment method required
The org needs billing set up before you can invite people to it.
Sample message
org.billing_required: Inviting people to acme needs billing set up first. Set up billing for acme, then invite them again.What to do: Set up billing for the org in its billing settings in the dashboard, then invite them again.
org.invitee_not_signed_inThe person hasn't signed in yet
This installation adds people to an org directly, and the address you named has not signed in to it yet. Valet adds a person only after their first sign-in. They join the home org then.
Sample message
org.invitee_not_signed_in: jo@example.com hasn't signed in to this installation yet. They join the home org when they first sign in; add them here after that.What to do: Ask the person to sign in, then add them to the org again.
org.creation_restrictedOrganization creation is restricted
This installation allows only platform superusers to create organizations.
Sample message
org.creation_restricted: Only a platform superuser can create an organization on this installation. Ask your Valet administrator.What to do: Ask your Valet administrator to create the organization.
org.invitations_disabledThis installation doesn't use invitations
This installation adds people to an org directly, so it has no invitations to accept. A person signs in through their company's SSO, and an Admin of the org adds them.
Sample message
org.invitations_disabled: This installation doesn't use invitations. Sign in through your company's SSO, then ask an Admin of the org to add you.What to do: Sign in through your company's SSO, then ask an Admin of the org to add you.
org.not_memberNot a member of the org
You named an org that doesn't exist or that you aren't in. Valet gives the same answer for both.
Sample message
org.not_member: You aren't a member of an org named acme. Check the name, or ask someone in acme to invite you.If you're in no org yet
org.not_member: Your Valet account isn't in any org yet. Create an org, or ask someone to invite you to theirs.What to do: Check the org name, or ask someone in the org to invite you. With no org yet, create one.
org.cap_reachedOrg limit reached
The org has as many agents, apps, or sites as its limit allows.
Sample message
org.cap_reached: acme has reached its limit of sites. Destroy a site you no longer use, or email support@valet.dev to raise the limit.Or
org.cap_reached: acme has reached its limit of sites. Destroy a site you no longer use, or contact your Valet administrator to raise the limit.Or
org.cap_reached: acme has reached its limit of sites. Destroy a site you no longer use, or contact help@example.com to raise the limit.What to do: Destroy one you no longer use, or email support@valet.dev to raise the limit.
org.ambiguousMore than one org matches
You belong to more than one org, and the request didn't say which. Either a name exists in several of your orgs, or the request named no org.
Sample message
org.ambiguous: support-bot exists in more than one of your orgs: acme, beta. Choose one of them, or set a default org.If you name no org
org.ambiguous: You belong to more than one org: acme, beta. Name one of them, or set a default org.What to do: Name the org (--org acme in the CLI), or set a default with valet orgs set-default.
org.permission_deniedRole lacks the permission
The role you hold in this org doesn't include the action. A Developer can build and run the org's sites, apps, agents, and skills; an Admin can also manage members, billing, and org-wide settings. An agent holds a role too.
Sample message
org.permission_denied: You can't delete the org in acme: that needs the Admin role, and you're a Developer.If an agent's role lacks it
org.permission_denied: support-bot can't change org-wide env vars in acme: that needs the Admin role, and support-bot is a Developer.If you have no role in the org
org.permission_denied: You can't invite members in acme: you have no role there. Ask an Admin to give you one.If you change your own role
org.permission_denied: You can't change your own role in acme. Ask another Admin.What to do: Ask an Admin to do it, or to change your role. When an agent was refused, ask a human Admin to perform the action.
org.last_adminThe org would have no Admin
The change would leave the org with no Admin: the org's only Admin tried to leave, was removed, or was made a Developer.
Sample message
org.last_admin: ana@acme.com is acme's only Admin, so they can't leave, be removed, or become a Developer. Make another member an Admin first.If you are the only Admin and leave
org.last_admin: You're acme's only Admin, so you can't leave. Make another member an Admin first.What to do: Make another member an Admin first, then make the change.
org.agent_role_fixedAgents must remain Developers
Assigning Admin was refused because agents can only hold Developer.
Sample message
org.agent_role_fixed: Agents must have the Developer role.What to do: Keep the agent as Developer. Ask a human Admin to perform administrative actions.
org.unknown_roleNot a role
The role name isn't one of the built-in roles, admin or developer.
Sample message
org.unknown_role: Name a role: admin or developer.Or
org.unknown_role: "owner" isn't a role. Use admin or developer.What to do: Use admin or developer.
Release policies
policy.unknown_checkerNo checker has that name
The policy names a checker Valet doesn't offer. Valet didn't save the policy.
Sample message
policy.unknown_checker: There is no checker named "snyk"; list the checkers to see the ones you can use.What to do: List the checkers you can use (valet policies checkers, the list_policies tool, or the Add policy dialog), then add the policy again.
policy.invalid_checkerAn organization checker's URL or headers can't be used
The checker's URL isn't an https address Valet can call, a header name or value is refused, or a header names an env var that isn't a secret in the organization. Valet didn't save the checker.
Sample message
policy.invalid_checker: The checker snyk's URL must use https.Or
policy.invalid_checker: The checker snyk's header Authorization names SNYK_TOKEN, which isn't a secret env var in acme; set it with valet env set SNYK_TOKEN=... --org acme.Or
policy.invalid_checker: The checker snyk's header Authorization names SNYK_TOKEN, which is a plain env var in acme; set it as a secret with valet env set SNYK_TOKEN=... --org acme.What to do: Do what the message says: fix the URL or header, or set the secret env var the header names with valet env set NAME=... --org <org>. Then save the checker again.
policy.checker_in_useA policy uses the organization checker
One or more policies name the checker, so Valet didn't remove it.
Sample message
policy.checker_in_use: acme's checker org:snyk is used by the policy "snyk", so it can't be removed. Remove the policy first.What to do: Remove the policies the message names, or point them at another checker, then remove the checker again.
policy.too_many_checkersThe organization has the most checkers it can have
An organization can have 20 checkers. Valet didn't add the new one.
Sample message
policy.too_many_checkers: acme already has 20 checkers, the most an organization can have. Remove a checker, then add this one again.What to do: Remove a checker the organization no longer uses, then add the new one again. Replacing a checker that exists always works.
policy.invalid_settingsThe checker refused the settings
The checker needs a setting you left out, or it rejected a value. Valet didn't save the policy.
Sample message
policy.invalid_settings: The "snyk" checker needs api_token.Or
policy.invalid_settings: The "snyk" checker refused those settings: Snyk rejected the token.What to do: Supply the settings the message names, then add the policy again.
policy.invalid_nameThe policy name is not valid
A policy name is lowercase letters, digits, and hyphens. Valet didn't save the policy.
Sample message
policy.invalid_name: "Snyk Deps" isn't a valid policy name; use lowercase letters, digits, and hyphens, such as "dependencies".What to do: Use a name such as dependencies.
policy.invalid_enforcementThe policy's enforcement is not valid
The enforcement or what the policy applies to is unknown, or a blocking policy has no severity. Valet didn't save the policy.
Sample message
policy.invalid_enforcement: A blocking policy needs a severity: info, low, medium, high, or critical.Or
policy.invalid_enforcement: "severe" isn't a severity; use info, low, medium, high, or critical.What to do: Use --monitor, or --block-at with info, low, medium, high, or critical.
policy.not_foundNo release evaluation has that id or name
The id or name matches no release evaluation of the service or organization.
Sample message
policy.not_found: support-bot has no release evaluation with that id.What to do: Run valet policies to list the organization's policies, or valet policies show for a service's release evaluation.
Releases
Resources
resource.detach_pendingResource is still detaching
An attach named a resource that the same app is still detaching. Valet finishes a detach on its own; the attach waits for it.
Sample message
resource.detach_pending: db is still being detached from web. Try again in a minute; nothing was attached.What to do: Try again in a minute. Nothing was attached.
Runtimes
runtime.image_override_unsupportedInstallation pins one runtime image
This installation uses one image for every organization and refuses organization image overrides.
Sample message
runtime.image_override_unsupported: org runtime image overrides are unavailable on this installation; clear the override or use the installation imageWhat to do: Clear the organization image override or use the installation image.
Sites
site.address_pendingSite published before its address can load
The site is published, but the org's web addresses are new and take a few minutes to start working.
Sample message
site.address_pending: This site is published, but your organization's web addresses are new and won't load for a few more minutes. Wait a few minutes before you open its address, because a browser that sees it fail may keep failing for a while.What to do: Wait a few minutes before you open the address.
site.claim_pendingA claim on the site started but didn't finish
Someone started claiming an anonymous site, and the claim stopped before it finished. The site's claim link answers with this until they finish.
Sample message
site.claim_pending: A claim on this site started but didn't finish. Only the account that started it can finish it. Sign in with that account and claim the site again.What to do: Sign in with the account that started the claim and claim the site again.
site.anonymous_disabledThis installation doesn't allow anonymous sites
The installation turned anonymous sites off, so it refuses to create, update, or claim one.
Sample message
site.anonymous_disabled: This installation doesn't allow anonymous sites. Sign in and publish the site to your org.What to do: Sign in and publish the site to your org.
site.not_publishedSite has no published version
The site exists, but nothing has been published to it.
Sample message
site.not_published: report has no published version yet, so it shows nothing. Deploy report to publish it.Visitors see
Nothing is published here yet. (site.not_published)What to do: Deploy the site.
site.wrong_accountSigned in with an account outside the site's org
A visitor signed in to a private site or app with a Valet account that isn't a member of its org. The message appears in the site's logs.
Sample message
site.wrong_account: Valet refused a signed-in account that isn't a member of the org that owns report. If they should see report, invite them to the org or share report with them.Visitors see
You’re signed in to an account that isn’t a member of this site’s org. Ask an owner to invite you, or sign in with another account. (site.wrong_account)What to do: Invite the person to the org, or share the site with them.
site.path_blockedAddress looks like a secret file and is never served
Valet never serves addresses that look like secret files, such as .env, .git, or .htaccess. Only the visitor sees this; there is no owner message.
Visitors see
Valet never serves addresses that look like secret files, such as .env, .git or .htaccess. (site.path_blocked)What to do: Rename the file if it isn't a secret. Never publish real secrets.
site.address_invalidAddress isn't valid text
The address holds bytes that aren't valid UTF-8 text, or a NUL byte, so it can't name a site, app, or channel. Scanners send these to probe for bugs. Only the visitor sees this; there is no owner message.
Visitors see
Valet can't read this address because it contains characters that aren't valid text. Check the link and try again. (site.address_invalid)What to do: Check the link. A browser never produces such an address from a normal link.
site.static_onlyStatic site received a form submission
A form or other request tried to send data to a static site, which only serves files.
Sample message
site.static_only: report is a static site, so it refused a POST to /contact. A form on a site can't submit to the site itself. Send the form to an app, or to another service that accepts it.Visitors see
This site can't accept form submissions. (site.static_only)What to do: Send the form to an app, or to another service that accepts it.
site.file_missingSite file couldn't be served
A file in the site's published version couldn't be served. Your site's files didn't cause it.
Sample message
site.file_missing: report's file img/logo.png couldn't be served. Deploy report again to restore it.Visitors see
This file couldn't be served. (site.file_missing)What to do: Deploy the site again to restore the file.
Skills
skill.invalidThe skill's SKILL.md can't be published
A create named a skill outside the name rule: 3 to 63 lowercase letters, digits, and single hyphens. Or a publish of a skill had no SKILL.md at its root, or its frontmatter was missing, malformed, over the Agent Skills limits, or named another skill. Nothing was created or published, and the skill keeps its latest version.
Sample message
skill.invalid: research's SKILL.md frontmatter isn't valid: it needs a name of lowercase letters, digits, and hyphens, and a description of at most 1,024 characters, between --- lines. Nothing was published; v3 is still the latest. Fix the frontmatter and publish again.If SKILL.md names another skill
skill.invalid: research's SKILL.md names research-mode, but the skill is research. Nothing was published; v4 is still the latest. Set name: research and publish again.If there is no SKILL.md
skill.invalid: research has no SKILL.md at its root. Nothing was published; v3 is still the latest. Add SKILL.md and publish again.If the name can't name a skill
skill.invalid: "Research Mode" can't be a skill name. Names are 3 to 63 lowercase letters, digits, and single hyphens. Nothing was created. Choose another name.What to do: Choose a name that follows the rule, or fix SKILL.md's frontmatter so it names the skill and describes it, then publish again.
skill.unpublishedThe skill has no published version
A skill was created but nothing has been published to it yet, so it can't be attached to an agent or read.
Sample message
skill.unpublished: research has nothing published yet, so it can't be attached. Publish research, then attach it.Reading the skill
skill.unpublished: research has nothing published yet. Publish research, then read it.What to do: Publish the skill, then try again.
skill.name_takenThe org already has a service of that name
Installing a catalog skill creates an org skill of the same name, and the org already has a service of that name, such as a site or another skill.
Sample message
skill.name_taken: acme already has a site named research, so Valet can't install research from the catalog under that name. Install it under another name, or rename the site.What to do: Install the catalog skill under another name, or rename the service that holds the name.
skill.rename_conflictAn agent already has a skill of the new name
An agent that attaches the skill already has a skill of the new name in its own source, so the rename would collide with it on the agent's next build. Nothing was renamed.
Sample message
skill.rename_conflict: research can't be renamed to deep-research, because support-bot already has a skill named deep-research in its source. Rename or remove that skill, then rename again. Nothing was renamed.What to do: Rename or remove the agent's skill of that name, then rename again.
skill.local_conflictThe agent already has a skill of that name
The agent's own source already has a skill with the name of the skill you attached, so the attached skill would collide with it on the agent's next build. Nothing was attached.
Sample message
skill.local_conflict: brand can't be attached to support-bot, because support-bot already has a skill named brand in its source. Rename or remove that skill, then attach brand again. Nothing was attached.What to do: Rename or remove the agent's skill of that name, then attach the skill again.
skill.in_useAgents still attach the skill
A skill can't be destroyed while agents attach it. Nothing was destroyed.
Sample message
skill.in_use: research is attached to support-bot and triage-bot, so it can't be destroyed. Detach it from each, then destroy it. Nothing was destroyed.What to do: Detach the skill from each agent that attaches it, then destroy it.
System settings
system_setting.superuser_requiredSuperuser role required
A Valet operator tried to change a system setting or the superuser role without holding the superuser role.
Sample message
system_setting.superuser_required: Changing system settings needs the superuser role. Ask a superuser to grant it.What to do: Ask a superuser to grant you the role, then try again.
system_setting.unknownNo system setting has that name
A Valet operator named a system setting that no Valet service declares.
Sample message
system_setting.unknown: No system setting is named "runtime.standbys". Run valet-ops settings list to see them.What to do: Run valet-ops settings list to see the settings, then use one of those names.
system_setting.invalid_valueA setting value is invalid
A Valet operator gave a system setting a value that fails its type, its bounds, or a rule that spans settings.
Sample message
system_setting.invalid_value: runtime.standby_count must be a whole number from 0 to 50; you gave 80.Or
system_setting.invalid_value: runtime.heartbeat_timeout must be longer than runtime.heartbeat_interval (30s); you gave 20s.What to do: Read the message for the rule the value broke, then set a value that meets it.
system_setting.stale_revisionA setting changed after it was read
Another operator changed the system setting after the caller read it, so the change was not applied.
Sample message
system_setting.stale_revision: runtime.standby_count changed since you read it: it is now 7, set by ana@valet.dev. Check the new value, then set it again.What to do: Check the new value, then set it again.
system_setting.reason_requiredA change needs a reason
A Valet operator changed a system setting or the superuser role without giving a reason.
Sample message
system_setting.reason_required: Give a reason for changing runtime.standby_count with --reason. It is kept with the change.What to do: Give a reason with --reason. Valet keeps it with the change.
system_setting.last_superuserThe last superuser can't be revoked
A Valet operator tried to revoke the only superuser, which would leave Valet with no one who can change settings.
Sample message
system_setting.last_superuser: ana@valet.dev is the only superuser, so the role can't be revoked. Grant it to another operator first.What to do: Grant the superuser role to another operator, then revoke the first.
system_setting.not_superuserThe person is not a superuser
A Valet operator tried to revoke the superuser role from someone who does not hold it.
Sample message
system_setting.not_superuser: bo@valet.dev isn't a superuser, so there is no role to revoke. Run valet-ops superusers list to see who holds it.What to do: Run valet-ops superusers list to see who holds the role.
system_setting.unknown_userNo Valet user has that email
A Valet operator tried to grant or revoke the superuser role for an email that no Valet user has.
Sample message
system_setting.unknown_user: No Valet user has the email cy@valet.dev. They need to sign in to Valet once before they can hold the role.What to do: Ask the person to sign in to Valet once, then try again.
system_setting.not_operatorOnly Valet operators can hold the role
A Valet operator tried to grant the superuser role to an address outside @valet.dev.
Sample message
system_setting.not_operator: guest@example.com isn't a @valet.dev address. Only Valet operators can hold the superuser role.What to do: Grant the role to a @valet.dev address.
system_setting.operator_requiredOperator role required
In a Valet Dedicated installation, a person without the operator or superuser role called an operator command.
Sample message
system_setting.operator_required: This needs the operator or superuser role. Ask a superuser to give you one.What to do: Ask a superuser to give you the operator role, then try again.
system_setting.unknown_roleNo platform role has that name
A platform role change named a role other than user, operator, or superuser.
Sample message
system_setting.unknown_role: "admin" isn't a platform role. Use user, operator, or superuser.What to do: Use user, operator, or superuser.
Valet
valet.internalA deploy or MCP tool failed on Valet's side
A problem on Valet's side stopped a deploy or an MCP tool call. If a deploy failed, nothing was deployed and the live release is unchanged.
Sample message
valet.internal: Valet couldn't finish deploying support-bot. This is on Valet's side, not yours. Nothing was deployed. Try again in a few minutes. If it keeps failing, email support@valet.dev.What to do: Try again in a few minutes. If it keeps failing, email support@valet.dev.