Troubleshooting

Most command errors print to stderr and exit 1. agentserve whoami and agentserve workflows runs wait use additional codes to distinguish outcomes; see Exit codes. The cases below explain failures whose cause may not be obvious from the message.

Start with agentserve whoami. It prints the resolved endpoint, workspace, and output format, and where each came from — which explains most surprises on its own — then checks the resolved key against the API. Add --no-verify to skip the check and stay offline.

A command targets the wrong workspace or deployment

Each setting resolves independently, and a flag beats the environment, which beats the profile. A stale AGENT_SERVE_WORKSPACE in your shell silently outranks the workspace you configured.

agentserve whoami

API-key pairing sets the default workspace selected on its approval page. After OAuth login, set one with agentserve configure --set-workspace <id>. The default target does not restrict your credential: use --workspace to reach another workspace that credential can access.

An error ends in — run: agentserve login --profile <name>

The API rejected the key with a 401. Either it was revoked, or it belongs to a different deployment than the endpoint you are pointed at — a key minted against a local stack will not authenticate against production. Check the endpoint before re-authenticating:

agentserve whoami --profile <name>

Could not reach https://agentserve.valnoraelric.com: <reason>

The request never got a response: DNS, TLS, a proxy, or a self-hosted stack that is not running. Confirm the endpoint the CLI actually used with agentserve whoami, and that it has the right scheme and port:

agentserve configure --set-endpoint http://localhost:3000 --profile local

A JSON flag rejects a value that looks like valid JSON

Your shell consumed the quotes. Wrap the whole value in single quotes, or read it from a file:

agentserve tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --filter '{"all":[{"field":"status","op":"eq","value":"open"}]}'
agentserve tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --filter @filter.json

A value looks truncated

table clips long cells to keep rows on one line. The data is not truncated — switch to a machine format to see it in full:

agentserve logs get 9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543 --output json

agentserve files get refuses to print to the terminal

Writing arbitrary binary to an interactive terminal can corrupt it, so non-text content has to go to a file or a pipe:

agentserve files get wf_8Kd2NpVrY6zTfQa3XwBmS -o ./image.png
agentserve files get wf_8Kd2NpVrY6zTfQa3XwBmS | shasum

A stored output format is invalid

A higher-priority source still wins, so you can repair the profile without editing the file by hand:

agentserve --output table configure --set-output json

A command is missing that the documentation describes

The docs track the current release, so a command that exists here and not in agentserve --help usually means the installed CLI is older than the feature. Compare agentserve --version against the published version and upgrade:

agentserve --version

Run agentserve update to update the active global installation. If this older release does not yet have the update command, upgrade with the package manager you installed it with — using a different one installs a second copy instead of replacing the executable on your PATH:

npm install -g @agentserve/cli@latest

pnpm add -g @agentserve/cli@latest

bun add -g @agentserve/cli@latest

yarn global add @agentserve/cli@latest

The CLI also shows an optional update notice through a cached daily check on eligible interactive invocations. Your command continues, and you choose when to run agentserve update. Checks stay quiet when stderr is redirected, in CI, and under npm exec or npx.

An update notice appears in output I am parsing

It should not: the notice is written to stderr, never stdout, so --output json piped to jq is unaffected. If something merges the two streams, silence it:

export AGENT_SERVE_NO_UPDATE_CHECK=1

Anything else

An unexpected error prints a stack trace. That is a bug in the CLI — please open an issue with the command you ran, the trace, and the output of agentserve --version.