Troubleshooting

A practical list of things that go wrong and how to fix them. Each entry is a symptom and the fix.

Quick reference

| Symptom | Fix | | --- | --- | | The model won't respond | The agent has no model credential yet. Connect it to Vercel. | | A Gateway billing or credit-card error in chat | The linked team has no AI Gateway billing. Relink against a team that does. | | Create-agent fails on a fresh machine | Make sure you're online; the app is provisioning Node 24 and Eve. | | The agent won't start | Check the dev-server logs in the Deploy tab, or run eve info. | | A red "N build errors" chip in the header | Click it; Capabilities shows the diagnostics and the file each points at. | | Self-modification enabled on an older eve | Upgrade eve, or remove the subagent and its dependency. | | "↑ x.y.z available" chip | A newer eve is on npm. Click to upgrade in place. | | Deployed chat is unreachable | Paste the Protection Bypass secret in Chat → Deployed and hit Test. | | 409 session_not_active in the console | Normal right after a session starts; Studio retries. Reset the thread if it persists. | | eve add failed with dependency_install | A peer-dependency conflict; Studio falls back to a direct install for Arcana. | | eve add exited with code 2 | Setup needs an answer. Run the printed continuation command. | | A new tool or hook doesn't appear | Reload the tab; Studio re-runs eve info --json. |

The model won't respond

An Eve agent's model routes through the Vercel AI Gateway, so it needs a credential before it can reply. If chat sends but nothing comes back, and you see a Not connected to Vercel (or Sign in to Vercel) banner, the agent isn't linked yet. Walk the in-app flow to sign in, link the project, and pull the token. See Connect to Vercel.

A Gateway billing or credit-card error in chat

The agent is linked and the token is present, but the first message fails with an AI Gateway error about billing or a missing credit card. The model bills the AI Gateway of the team you linked against, and that team has no billing set up. If your account has several teams, the banner's team selector picks which one; connect again with a team that has Gateway billing (or add billing to the current team in Vercel), then send again.

Create-agent fails on a fresh machine

On a machine that has never run Studio, the app has to provision its own Node 24 runtime and install Eve (npx eve@latest) before it can scaffold anything. This step downloads packages, so it needs a network connection. If create-agent fails on a brand-new machine, make sure you're online and try again. The first run takes a minute while it fetches everything; later runs reuse what's already there. Watch the "working…" spinner and elapsed timer to confirm it's still making progress.

The agent won't start

If the agent's status pill stays stopped or flips back after you hit Start, the local eve dev server failed to boot, usually a code or config error in the agent folder. Open the Deploy tab and read the dev-server logs pane, which streams that server's output and shows the actual error. Studio's structure refresh runs eve info --json, which reports Eve's discovery diagnostics (errors and warnings with the file that caused them); running eve info in the agent folder shows the same report. Fix what it reports (often a type error, a missing environment variable, or a capability file with the wrong shape) and start again.

A red "N build errors" chip in the header

Studio runs eve info --json whenever it refreshes structure, and Eve's discovery diagnostics come back with it. When any of them is an error, the header shows a red N build errors chip; the dev server may still start, but the offending capability isn't loaded. Click the chip to open Capabilities, where each diagnostic names the file and the problem (a missing description, an export with the wrong shape, an extension whose eve peer range doesn't match). Fix it, hit reload, and the chip clears. Running eve info in the agent folder prints the same report.

Self-modification enabled on an older eve

@eve/self-modification is pinned to the eve 0.49 line. If it was installed into an agent on an older eve, eve info reports a discovery error for agent/subagents/self-modification/ and the build-error chip appears. Two fixes:

Upgrade eve with the header chip (see Keep eve current); the subagent starts working once eve matches.
Remove it: delete agent/subagents/self-modification/ and uninstall the @eve/self-modification dependency (pnpm remove @eve/self-modification, or the npm/yarn equivalent).

Studio now checks the eve version before offering Enable, so this only affects agents set up earlier.

Deployed chat is unreachable

If chat works against Local but a Deployed target can't connect, click Test in the Deployed target bar; the failure names the cause. "Blocked by Vercel Deployment Protection" means the production URL is gated: generate a Protection Bypass for Automation secret in Vercel → Project → Settings → Deployment Protection, paste it into the secret field, Save, and test again. "Route auth rejected the request" means the agent's own auth refused the call: pull env from the Environment tab to refresh the OIDC token. "Couldn't reach the URL" means the URL is wrong or the deployment is down; use Detect to fill it from the linked project. See Deploy to Vercel.

`409 session_not_active`

Creating a session returns as soon as Eve's Workflow accepts the run, before the session is ready to take a second message. If a follow-up arrives in that window, or targets a session that has been reset or has finished, Eve answers 409 with { "code": "session_not_active" }. Studio waits for the session.waiting event before sending follow-ups and retries a 409 a few times with backoff, so you normally never see it. If the retries are exhausted, Chat says the thread's session is no longer active and points you to ⋯ → Reset session, which archives the thread and opens a fresh one; the old thread stays readable under Archived.

`eve add` failed with `dependency_install`

A registry install runs your package manager to add the item's dependencies. When that step fails, eve add rolls the install back and reports failureCode: "dependency_install"; the console shows the package manager's error. The common cause is a peer-dependency conflict: the package declares an eve peer range that doesn't include the version your agent is on. On npm this is a hard error; pnpm only warns.

For Arcana, Studio handles it: it installs @kybernesis/arcana with the agent's package manager (npm install --legacy-peer-deps, pnpm add, or yarn add) and writes agent/extensions/arcana.ts itself, then continues with the env vars; the result panel says Fallback used. With @kybernesis/arcana 0.4.1 on eve 0.49 the install succeeds directly, so this only kicks in when a package's peer range lags a new eve release. For other items, the failure panel suggests the same: install the package by hand with --legacy-peer-deps and rerun the item with eve add <item> --skip-install to write its files.

`eve add` exited with code 2

Exit code 2 means the item's setup needs an answer Studio couldn't supply, or has an unmet prerequisite (most often "run eve link first"). The final NDJSON event names the question and prints a safe continuation command (eve add <item> --skip-install --answer key=<value> …). Studio's panel reads Setup needs an answer Studio can't guess, shows the prerequisite, and prints that command with --non-interactive stripped so the prompts can be answered; run it in a terminal from the agent folder, or connect the agent to Vercel and click Install again. Never put a secret in an --answer; use the environment variable the item documents.

A new tool or hook doesn't appear

Eve discovers capabilities from the filesystem. If you added a tool, hook, skill, subagent, or memory slot outside the app and it isn't in the list, hit the reload button in the tab header. Studio re-runs eve info --json, which regenerates the discovery and compiled manifest without booting a server. If it still doesn't show, eve info will have reported a diagnostic explaining why (a missing description, a bad export, a file in the wrong folder).

Slack or Buzz doesn't answer

Both reach the deployed agent only. Deploy first, then test from the platform. For Slack, check the channel file references the same connector that's attached for triggers (Connecting Slack); for Buzz, check the bridge log (Connecting Buzz).

Still stuck?

Re-check Connect to Vercel; most "nothing happens" issues trace back to a missing model credential.
Read the Deploy tab's command-output console and dev-server logs; the real error is usually there.
Run eve info in the agent folder; it's the fastest way to see what Eve discovered and why something was rejected.
Confirm you're on a current build. Studio is built for eve 0.49 and newer, installs Eve via npx eve@latest for new agents, and offers an in-place upgrade for existing ones (Keep eve current).