Error codes
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.
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.Or
agent.boot_timeout: support-bot didn't finish starting within 3 minutes. support-bot stopped after 5 failed starts.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.
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.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.
Builds
build.failedA build step failed
A command in the build exited with an error, such as a missing package. The build log names the step.
Sample message
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.
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)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.
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.Or
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.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.Or
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.
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 --force).
deploy.draft_openAnother deploy is in progress
The agent has changes open from another deploy that hasn't finished: someone else's, or an earlier one of yours.
Sample message
deploy.draft_open: This agent 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 (valet drafts discard <id>) or replace them (valet deploy --force, or discard_draft: true over MCP).
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_movedAgent changed during the deploy
A person, or the agent itself, changed the agent while you were deploying. Nothing was deployed, and your changes are kept.
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.What to do: Deploy again.
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.Or
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, and sites in an org share one set of names, and something already uses this one.
Sample message
name.taken: acme already has an agent, app, or site named report. Choose another name.Or
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.
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.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, and some names that mail and web clients treat as special.
Sample message
name.reserved: "architect" is reserved. Choose another name.What to do: Choose another name.
Organizations
org.billing_requiredPayment method required
The org needs a payment method before it can run agents or apps.
Sample message
org.billing_required: Your organization needs a payment method before it can run agents or apps. Add one in its billing settings, then deploy again. Nothing was deployed.What to do: Add a payment method in the org's billing settings in the dashboard, then deploy again.
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.Or
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.What to do: Destroy one you no longer use, or email support@valet.dev to raise the limit.
org.ambiguousName exists in more than one org
You belong to more than one org that has something with this name, and the request didn't say which.
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.What to do: Name the org (--org acme in the CLI), or set a default with valet orgs set-default.
Releases
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.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.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.
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.