Troubleshooting

Signing in over SSH#

exeora login opens a browser on this machine and waits for a callback on localhost. That cannot work in an SSH session, a container, or a machine with no display. Run exeora login --code instead. The terminal prints a URL and a code; open the URL on another device, type the code shown here, and the CLI finishes signing in. Only enter a code displayed on a terminal you control.

LOCAL_EXECUTOR_OFFLINE#

A machine of yours is off, or no CLI is connected on it. Which machine depends on the call: the one that holds the workspace it named, or the project's default location when it named none. Run exeora connect on that machine and leave it running.

It fails immediately rather than waiting, on purpose. Nothing is queued, because a command landing hours later when a laptop wakes up is worse than one that never ran.

The same code, with a message that says so, is the answer when the machine of the default location was revoked. The message lists where the project still lives. Work in a workspace there, or choose a new default location on the project's page or with exeora project default.

EXECUTOR_WAKING#

The call was for an instance on Exeora Cloud, the instance was asleep, and it did not come up in time. Nobody has to start anything: send the same call again after a few seconds. If it keeps happening, look at the instance under Machines, on the Exeora Cloud tab. One that failed says why and what to do, and Retry sets it up again.

With the message "The instance for this project's root on Exeora Cloud had been destroyed, and another is being made", the cause is another one. Exeora Cloud is the project's default location in state no instance, because the instance of the project root was destroyed or the last machine that held the project was deleted. The call asked for the project root, which is what makes the instance. Send the same call again in about a minute. Start instance on the project's page and exeora project default <slug> --on cloud ask for the instance ahead of the call.

When the instance cannot be made, the answer is LOCAL_EXECUTOR_OFFLINE with the reason. The usual one is that every instance of the plan is in use: destroy one under Machines to make room, then send the call again.

"This project lives nowhere at the moment"#

The project has no location. The last machine that held it was deleted, or its only location was removed, and it is not on Exeora Cloud. It is still a project, with its MCP URL, its policy and its clients, and nothing can serve a call to it. The answer carries the code LOCAL_EXECUTOR_OFFLINE.

Give it a place again. Run exeora project add . in a checkout of it, or exeora project add owner/repo on a machine. Or add a location with exeora project locations add <slug> --on <machine|cloud> or Add location on the project's page. An agent can call create_workspace with where set to cloud, which puts the project on Exeora Cloud. See a project that lives nowhere.

A clone failed on a machine#

The first workspace asked for on a machine that holds no copy of the repository clones it into that machine's projects folder. When that fails, the location shows as failed on the project's page with the reason, and the call that asked is refused with it. Run from the machine itself, exeora workspace create also prints the line git gave. Nothing is left behind by a clone that failed, so the next attempt starts clean.

• The repository refused access, or was not found. A private repository looks the same as a missing one to a machine that has no access to it. A clone tries a short-lived token from Exeora when the project is connected to GitHub, then the git credentials of the machine over https, then ssh, and none of them can stop to ask for a password. Connect GitHub, or set up git credentials on that machine, then ask for the workspace again.
• A directory is in the way. The clone goes to <projects-root>/<slug>. A checkout of the same repository at that path is adopted. Anything else there is refused without being touched, with a message that names it. Move it somewhere else, or choose another folder with exeora config set projects-root <path>.
• The projects folder cannot be created or written to. Choose another one the same way.
• The machine could not reach the host, or the clone timed out. A clone is stopped after thirty minutes. Check the connection of that machine, then try again.
• The machine is not connected, or its CLI is too old to clone. Run exeora connect there, or exeora upgrade. Cloning by hand and running exeora project add in the checkout ends in the same place.

A call that ends before a long clone does not stop it. The clone goes on, the machine tells Exeora when it is ready, and list_workspaces or the project's page says so.

An instance failed because gh could not be installed#

The instance is failed with "The GitHub CLI (gh) could not be installed on the machine", followed by the reason. gh is the one tool an instance is not handed over without. The reason is what the instance said: the download failed, no time was left, the checksum of the download did not match, or there is no build for the architecture of the machine.

Most often the cause is a network that is back a minute later. Press Retry on the instance, from the project's page or from Machines under the Exeora Cloud tab. When the same reason comes back, the details on the row hold what the instance printed: write to hello@exeora.dev with them.

A tool is missing on an instance#

Three causes, and About this instance on the row of the instance tells them apart:

• It could not be installed. The row says how many tools could not be installed, and About this instance lists the tool under Failed or Skipped with the reason. The instance is ready without it. Tools are installed only while an instance is set up, so install the tool from the install script, or destroy the instance and start it again to have every tool attempted again.
• The instance was made before the tools existed. About this instance lists no tools at all. Push what the instance holds, destroy it and start it again.
• The tool was never one of them. Docker and database servers are not installed, and neither is anything only one repository needs. What an instance comes with is the whole list. Install anything else from the install script.

The install script failed#

The instance is ready, and its row carries a warning such as "The install script failed (exit 1). It came from the repository. Fix the script, then run it again." Details under it shows the end of what the script printed. The usual causes:

• A command in the script failed. The exit code in the warning is the script's own, and the output says which command it was.
• Something asked a question. A script has no terminal to ask on. Give each command the flag that answers ahead of time.
• It ran out of time. The warning says so, and the output ends with a line that starts with [exeora] Stopped. The limit is 20 minutes. Take out what the instance does not need to be worked in.
• It ran out of memory. The output ends with a line that starts with [exeora] Killed and names the limit. Build fewer things at once.
• A tool it calls is missing. See a tool is missing on an instance.

Fix the script where the warning says it came from, then press Run again. A script on the project's page is used as it is at that moment. A file of the repository is read from the checkout of the instance, so the fix has to be pulled there first. A command an agent ran while the script was failing may have found dependencies missing: run it again after the script has ended well.

The resume script failed or ran out of time#

The instance is ready, and its row carries the warning. The resume script has 2 minutes, because it runs in front of the first command after a sleep. One that ran out of time was stopped at that limit.

• It does work that belongs in the install script. Installing dependencies is done once, and the disk keeps it through a sleep. Leave to the resume script only what a sleep takes away, such as a service that has to be running.
• It waits for what it started. Start a service in the background, so that the script itself ends.
• It fails the second time it runs. The script runs at every resume, and one resume can run it more than once. Write it so that finding its work already done is not an error.

Fix the script, then press Run again on the row. Details shows the end of what it printed.

"Scripts do not run on this instance"#

About this instance says "Scripts do not run on this instance, which was made before they existed", and Run again is refused with "This instance was made before scripts existed". The instance was made with a CLI older than 0.19.0, which is the first that runs scripts. It keeps working as it did, without them, and gh is not signed in there.

Destroy the instance and start it again. Push what it holds first, because the instance is the only copy of work that was never pushed. A workspace is started again by creating it on Exeora Cloud on the same branch, and the project root with Start instance on the project's page.

slug_taken on exeora project add#

A project with that name already lives on another machine, and the directory you are adding is not a checkout of the same repository. Exeora refuses rather than moving the project to this machine, which would leave the other one holding nothing. Add the directory under another name with --slug, or remove the other project first.

If the two are meant to be the same project, they need the same remote: a checkout whose remote is already a project joins it whatever the directory is called. A project added by a CLI older than 0.18.0 has no repository on record until exeora sync runs on the machine that holds it.

GitHub could not be connected#

The way back from GitHub ends on Settings with the outcome. When it failed, the address carries a reason and the dashboard says it in words:

Later on, the dashboard asking you to connect again means GitHub stopped accepting the authorization your account had. See when access is lost.

gh says it is not signed in#

On an instance, a gh command that needed to be signed in and was not ends with a line that starts with exeora: gh is not signed in: and gives the reason. gh auth status prints the same line.

The answers that say no are remembered on the instance for a minute, so that a loop calling gh does not ask every time round. After mending the cause, wait a minute before running the command again. An instance made with a CLI older than 0.19.0 never signs gh in: see "Scripts do not run on this instance".

gh cannot read issues, checks or workflow runs#

gh is signed in, and GitHub refuses gh issue list, gh pr checks or gh run list. The installation of the Exeora GitHub App that holds the repository has not accepted the permissions the app added. A push that changes a file under .github/workflows/ is refused by GitHub for the same reason.

Open Settings. The GitHub card shows a notice beside each installation that has permissions pending. Review on GitHub opens the installation, where its owner accepts them. On an organisation that is one of its owners: ask them when you are not one. See accepting permissions that were added.

The gateway closed the connection#

Two reasons, and the message says which:

• The machine was revoked from the dashboard. Registering it again takes exeora connect --reset.
• The protocol version is out of range. Run exeora upgrade. It replaces the installed binary with the newest release. Adding to the protocol does not normally break an installed CLI, so this is rare; when it happens the message names both versions.

A change is refused with "not approved"#

The project asks for every change to be confirmed and nobody answered within ninety seconds. Look at the terminal running exeora connect, or at the banner in the dashboard.

If that machine has no terminal, which is the case under systemd or in a detached tmux pane, the question only ever goes to the dashboard. Keep a tab open, or turn confirmation off for that project.

A command is refused as shell syntax#

The project has a command list in force, and the command carries a pipe, a redirect, a substitution or a chain. Any of those makes the first word a poor description of what the command will do, so it is refused rather than matched.

Rewrite it as a plain command, or, if the project is one you would have left open anyway, turn on shell and accept that both lists become suggestions. See what a project allows.

The agent cannot see a tool#

Two things hide a tool. The project's tools list may not name it, which is a setting in the dashboard. Or the connected machine may be running a CLI too old to have it, since the gateway only advertises what the executor announced: update the CLI.

A multi-project call does not name a project#

Only on the account URL, and only when a connection reaches several projects. Call list_projects to see the valid targets, then pass a project slug or id on the tool call. A connection given exactly one project may omit it because there is nothing to choose between.

Project selection is not stored on the client. Repeat the same project value on every related call, including calls that read, write to or stop a process started earlier. This lets separate conversations use separate projects at the same time.

"This connection has not been given access to any project" means every project it had was revoked or deleted. Authorize the client again from its own settings and tick the projects it should reach; if it still appears under Clients in the dashboard you can give it projects back there instead.

The account URL offers a tool a project cannot run#

With several reachable projects, tools/list cannot assume one target, so a client can see a tool that one project's machine does not serve. A call naming that project fails rather than doing something unexpected. Update the older machine's CLI if it should offer the same tools.

A project the gateway does not know#

exeora status marks these, and they happen when a project was removed from the dashboard, or taken off this machine as a location, while this machine was not looking. exeora sync reconciles the two.

A process disappeared#

Processes started with start_command die when the CLI disconnects, including across a reconnect. That is deliberate: a dev server nobody can reach, read or stop is not a feature. Start it again after the connection comes back.

No keychain on this machine#

Most Linux servers and CI containers have no secret service. The CLI falls back to a 0600 file under $XDG_CONFIG_HOME/exeora/ and says so when it happens. Nothing else changes.

Linux says GLIBC_ is not found#

The published Linux binary is linked against glibc 2.31, which is Ubuntu 20.04 LTS. A machine older than that, such as Ubuntu 18.04, Debian 10 or CentOS 7, will refuse to start it. Upgrade the distribution. If the machine can run the repository's required Rust toolchain and build dependencies, a native source build may work, but systems with glibc older than 2.31 are not supported.

The Windows installer says x64 is unsupported#

Exeora's Windows release is an x86_64-pc-windows-msvc executable. The installer checks the native Windows architecture, not the bitness of the PowerShell process running it. A 32-bit PowerShell on 64-bit Windows reports PROCESSOR_ARCHITECTURE=x86; Windows exposes the native AMD64 value in PROCESSOR_ARCHITEW6432. The installer uses that override when it is present, so running the command from 32-bit PowerShell no longer produces a false unsupported-architecture error.

ARM64 Windows is still not accepted because Exeora does not publish an ARM64 CLI binary. The error now includes the detected architecture so that a genuine platform mismatch can be distinguished from the old process-versus-OS detection problem.