Troubleshooting

Almost everything that goes wrong with AETHER Coder goes wrong on the first message of a task, because the connect form does not test anything while you fill it in. That is inconvenient but useful: it means a failing first message is nearly always one of a small number of things, and this article is that list.

Find your symptom below. Each entry gives the usual cause and the fix.

"Authentication failed", or a 401 on your first message

Cause. One of the two credentials is wrong. Either the Access Token is missing, mistyped, expired or revoked, or the API Key is not a valid GUID, or it is a well-formed key that matches no agent — a typo, a key copied from a different environment, or an agent that has since been deleted.

Fix.

1. Open Settings from the gear icon, then the API Configuration tab.
2. Re-enter your Access Token. It must begin aeth_; if the value you are pasting does not, it is not an access token.
3. Re-enter the API Key from the agent's published page.
4. Send the message again. Changes apply to your next message — nothing needs reloading.

If it worked for weeks and has just stopped, the token has expired or somebody revoked it. Generate a fresh one; see Access Tokens.

"Not found", or the request never reaches AETHER

Cause. The Base URL is wrong. The two usual mistakes are leaving off the /api/code/v1 path, and using http where the platform redirects to https.

Fix. Correct the Base URL in Settings → API Configuration so that it reads like https://your-aether-host/api/code/v1 — the host on its own is not enough, and nothing should follow /api/code/v1. Confirm the host with your administrator if you are unsure; see Connect to AETHER.

"This agent's budget has been exceeded and further requests are currently blocked"

Cause. The request reached AETHER, but the agent's budget — or its owner's, its team's, its business unit's or the organisation's, further up the chain — is exhausted. The platform checks the budget before it serves the request, so the failure surfaces as a rejected message rather than a partial or corrupted edit.

Fix. Ask your administrator to raise the budget, or wait for its period to reset — see Cost, Budgets & Auditing. Files already written to your workspace are unaffected; the agent simply stops replying until then. Trying again immediately will not help: the budget check runs before the request, so a retry meets the same wall. Retrying does make sense for a separate, transient model-quota failure — ask your administrator to check the agent's model configuration if the message points there instead.

You cannot find anywhere to enter your connection details

Cause. The panel has opened on something other than the AETHER connect form.

Fix. If the first screen you see is not the AETHER connect form, open Settings from the gear icon, go to API Configuration, and enter your three values there instead:

Leave Model ID as aether. The connection works exactly the same way whichever route you take, and this is also where you change the values later.

The agent replies in prose instead of editing files

Cause. The agent's system instructions in AETHER conflict with the coding protocol each request carries. Conversational or greeting-style guidance — "always introduce yourself", "reply warmly" — competes with the instruction to use tools, and prose wins.

Fix. This is fixed on the platform, not in the editor. Keep a coding agent's instructions factual and task-focused: standards, constraints, house rules. Conversational guidance belongs on chat agents. See Enabling Code Agent Mode.

The agent says it changed a file, but nothing changed

Cause. An edit was proposed and never approved — the diff was rejected, dismissed, or is still waiting.

Fix.

1. Look for an open diff view with Save and Reject above it, and answer it.
2. Check the conversation for a rejection you made earlier in the task.
3. Use Compare on a checkpoint to see exactly what the workspace has and has not received.

See How the Agent Edits Your Code.

A command appears to hang

Cause. The command ran, but the shell never reported that it had finished, so the agent is still waiting for a signal.

Fix. Raise the shell integration timeout in Settings → Terminal. That is the usual remedy, and heavily customised shells on Windows are the usual culprit. If it persists, change the terminal execution mode, or use Proceed While Running for commands that are never meant to exit, such as a watch build or a dev server.

Images you attach are ignored

Cause. Either more than four images were attached to one message, or the agent's model has image support switched off.

Fix. Attach at most four images per message, and no more than 20 images and files combined. If a single image is still ignored, ask your administrator whether the agent's model accepts images. See Limits & Known Behaviour.

Responses stop part-way through a long task

Cause. The context window filled up. Everything in the task — your messages, the agent's replies, every file read and every command's output — is carried on every turn.

Fix. Condense the conversation using the compaction control on the task header or /smol, and switch on Auto Compact for long work — it is off by default. Better still, start a fresh task with /newtask, which carries the conclusions forward without the transcript. See Context: Mentions, Images & Focus.

The agent refuses with a message about Code Agent mode

Cause. Your credentials are fine, but the agent has not been switched into Code Agent mode in AETHER, so the coding endpoint refuses to serve it.

Fix. Ask whoever owns the agent to enable it and publish the agent. It applies to your next message — nothing needs reinstalling and you do not need to reconnect. See Enabling Code Agent Mode.

A red card says your message was blocked

Cause. Not a fault. The platform scanned the message before sending it and found personal information or a credential, and this agent's policy is to refuse rather than mask it. The message never reached the model, which is why the task cost nothing.

Fix. Read the sentence on the card: it names what was found. Take that value out and send again — or point the agent at the file by name instead of pasting its contents, since what the agent reads for itself is redacted rather than refused. There is no retry button because retrying identical text always fails the same way, and no written-reason override from the editor. If the value is not personal data at all, it can be allowlisted for that agent. If it was a real key, rotate it. See PII Guard and Secrets Guard.

The Remote tab shows no QR code

Cause. No personal access token is configured. The tab draws the code from the token in API Configuration, so with nothing there it shows Access Token Missing instead.

Fix. Paste your aeth_… token into API Configuration — the extension picks it up within a few seconds, without a restart. If the code appears but the phone cannot open it, the phone is not on a network that can reach your AETHER host. See Remote Developer View.

Note: if none of the above matches, check the three connection values once more before anything else. They are entered by hand, they are never validated as you type, and a trailing space on a pasted token looks exactly like a platform outage.

Next steps

• Settings Reference — every option in the panel's Settings view.
• Limits & Known Behaviour — the behaviour that is expected rather than broken.
• Connect to AETHER — the three values and where they come from.