Troubleshooting and FAQ

Start with geo doctor#

geo doctor

Prints one line per check, each ok, fixed or needs you: the adapter bundle, Docker, disk space, your records, evidence integrity, checks left running by a process that ended, and leftover containers, networks and images. Add --fix to also set Docker up when it is missing or stopped (it shows the exact commands and asks first). Add --no-fix to change nothing, --quiet to print only what is not fine, and --json for a machine-readable result.

Docker is missing, stopped or too old#

Geometer says which of these it found: Docker is not installed, not running, older than version 24, or it could not read Docker's state.

• Not installed. In a terminal, run geo doctor --fix: on a Mac with Homebrew and no Docker it shows the commands that install Colima and the Docker command line, asks Run them now? [y/N] and runs nothing until you say yes. The Docker card in the workspace does the same with a button, and your coding assistant sends you to that card. Without Homebrew, install Docker Desktop; on Linux, install Docker Engine. See Docker and Colima.
• Not running. Run geo doctor --fix to start Docker Desktop or Colima (it asks first), or start it yourself, or start the Docker service on Linux, then check again. The Docker card updates by itself.
• Too old. Upgrade to Docker 24 or newer.
• Linux: no services found, or builds fail. Both docker compose version and docker buildx version should answer. Install the compose and buildx plugins.
• Linux: permission denied. Your user must be able to talk to Docker without sudo. Geometer does not use sudo.
• "Nothing was run. When you are ready, run `geo doctor --fix` again to set Docker up." You answered no (or pressed Enter) to Run them now? [y/N]. Nothing was installed or started. Run the command again when you are ready, or set Docker up yourself.
• "Nothing was run: Geometer has no command it can run on this computer." There is no Homebrew on the Mac, or this is Linux. Geometer shows instructions instead, because it never runs commands that need administrator rights. Follow them, then check again.
• The commands ran but Docker still does not answer. Geometer shows what the command printed and says to fix what it names, then run geo doctor --fix again.
• "Docker is ready, but `geo` could not start the command again." Docker is now running, and only the second start of your command failed. Run the same command once more.
• Nothing asked, just an exit code of 3. In a script, in CI or without a terminal, Geometer never asks and never installs. It prints the message with the one thing to do. See Install.
• After installing Colima. Geometer finds Colima's socket and Homebrew's folder when it starts, so the next check after an install can use it. If it does not, quit and open Geometer again, or run geo open again.
• `geo ci` exits with 3 and names Docker. The runner has no usable Docker. In a Docker-image CI step, check that the socket is mounted. See Run kept checks in CI.

A wrapped MCP server, a try or a recording says no#

geo mcp wrap, try and record put a relay in front of your servers. When something is missing, every request to the server gets an error that says why and that nothing was sent to the real server. Fix the named thing, or put the server back with geo mcp mode <server> pass or geo mcp unwrap --write.

• "Geometer found no MCP configuration in this folder." Name the file: geo mcp wrap path/to/mcp.json. Servers defined in your code (MCPServerStdio, MCPClient, MultiServerMCPClient) are not edited; geo mcp wrap prints the change to make by hand.
• Nothing changed for my agent after wrapping. Restart your assistant or agent. The mode is read when a wrapped server starts, so one that was already running keeps the old behaviour.
• "Try mode is set but no simulated service is recorded for it", or "The simulated service of this try is not running (the try has ended)." A try ends by itself (30 minutes unless you say --for 10m), and the servers go back to pass. Run geo mcp try again. Nothing was sent to your real server.
• "Say which pack to try with." Geometer could not tell which simulated service fits your servers, or more than one does. Name one with --pack, for example --pack payments. A try uses one pack at a time.
• "not simulated" in a try. The pack does not simulate that tool, so the call got an error and nothing reached the real server.
• "Guard mode is set but its configuration is missing", "Guard mode needs GEO_GUARD_AGENT_TOKEN" or "`geo-guard` was not found". Guard mode needs its file, the agent's credential in the server's env and geo-guard next to geo. Or set the server back to pass. See Put Geometer in front of your MCP servers.
• "There is no try to keep yet." geo mcp try keep keeps the last try that recorded your model's answers. Run geo mcp try --record-model -- <your agent> first.
• "There is no kept try check in this project." geo mcp try replay needs a kept try. Keep one with geo mcp try keep.
• A replay says "Different from when it was kept", or a kept try makes `geo ci` exit 2. The rules did not come out as they did when the check was kept. A recorded model answer fits only the exact request it was recorded for, so an agent whose prompt holds a time or a random value no longer matches its recording, and the replay says so. Run geo mcp try --record-model again and keep a new check.
• "Say which server to record", or "No wrapped servers are known for this project yet." Name the server (geo mcp record <server>, the names are in geo mcp tools) or use --all, after geo mcp wrap --write.
• A check says it could not tell because of "not simulated: not in the recording". A twin only knows what the recorded session showed. Record again while your agent uses more of the service, then run geo mcp twin <server> again.

A framework agent: not found, "not tested" or "not observed"#

Works with says, framework by framework, whether Geometer sees an agent's tools: Supported, Partial or Not yet.

• The report says the hook was not tested with this version of the framework. The agent ran, and Geometer watched its tools, but only the versions listed on Works with were tested. The line says how complete the capture is. Treat the result as less certain.
• The report lists tools as "Not observed". Hosted tools (a provider's web search or code execution), tools the application answers and, for the Claude Agent SDK, the built-in tools of the Claude Code process are not seen. Only function tools that run in your agent's process, and web and MCP calls, are.
• My framework is not listed, or my agent is Java, .NET or Go. These are Not yet. If the agent runs in its own Docker image, Geometer still checks its web and MCP requests and its model calls, but not tools that are plain functions inside it.
• A Python project fails to install or import. When the project does not say which Python it needs, Geometer uses .python-version if there is one, else the lower bound of requires-python when that is above 3.12, else 3.12, and a project with old pins can fail on 3.12. Add a .python-version file that names the version your project needs, then check again.
• The agent is not found at all. See No tasks found, or an unsupported project: geo env plan --agents shows what Geometer found and the gaps.

macOS will not open the app#

The alpha is not signed by Apple, so macOS refuses it the first time. Open System Settings, then Privacy & Security, scroll to the message about Geometer, click Open Anyway and confirm. Or in Terminal:

xattr -dr com.apple.quarantine /Applications/Geometer.app

You do this once for each version. If the app is on an Intel Mac, it will not run: the alpha is built for Apple silicon only. The terminal installer refuses an Intel Mac and installs nothing.

The sign-in link does not work#

• "That sign-in link was already used or has expired." A link works once and expires after ten minutes. Run geo open again to get a new one, or open the Mac app.
• "This page needs the one-time link Geometer gave you." You opened the workspace's address without signing in. Use the link that geo open printed.
• You clicked the link on another page, such as a chat or a GitHub issue. That works: you may see a short "Opening Geometer" page and then the workspace. If you see "Geometer did not open this page", the request came from somewhere the workspace does not accept. Use the link printed in your terminal, or run geo open again.
• "Geometer is not answering". The workspace's server stopped. Close the window and open it again, or run geo open again.
• A copied link opens a blank or error page. Make sure you copied the whole link, including the code at the end. If in doubt, run geo open again for a fresh one.

No tasks found, or an unsupported project#

When Geometer cannot find an agent task, or cannot start your app, it says what was missing on the project page under What Geometer could not do here. Then only your own tests can run, and a clean result says that none of your tests failed, not that nothing can go wrong.

If the page says "Geometer could not finish working out how to run your agent", that is not the same as "no agent": something went wrong while it was reading your project, and the reason follows the sentence. Choose Check this project again; that reads the project again instead of reusing the failed answer.

Geometer can run agents whose tools it can find and simulate. When it cannot, it says what is missing instead of reporting a clean result. What you can do:

1. Run geo onboard and read what it worked out, where it found each fact, and the one question left. Answer the question in the workspace or with --answer ID=TEXT.
2. Run geo env plan --agents to see the agents, the model and tool endpoints it found, and the gaps.
3. Write declarations for tools, tasks and rules in .geometer/, or in a folder outside your project that you pass with --declarations. geo onboard --save-declarations DIR exports what Geometer inferred, as a starting point you can review and edit.
4. Report a project that Geometer missed. See Report a problem.

The first check is slow, or looks stuck#

The first check downloads container images, usually a few hundred megabytes, and installs your project's dependencies. Later checks reuse them. Each line on the check page is timed from the start. Open Under the hood to see the processes and containers that are running and the network activity. If a check ends with "Stopped before completion", the check's process ended unexpectedly; its containers were removed and you can start it again.

"Couldn't run: your agent failed at start" or "Couldn't tell: the agent made no tool calls"#

Geometer started your agent's task and no run reached a tool call, so nothing was tried. It is not a clean result, and it exits with 3. For "failed at start", the line shows what your agent printed when it exited: run your agent's start command yourself, fix that, and check again (a missing package or a Node version your dependencies do not support are common). For "made no tool calls", run the task yourself and check that it reaches one of its tools; a task that only chats has nothing for Geometer to fault. No certificate is offered from such a check.

"Couldn't run" one of my project's own test commands#

Geometer runs your project's own test commands in a sandbox. When one exits with an error within a minute, writes no per-test report and its output says something is missing (for example a Playwright browser that is not installed, a program, a module or a network service), the check says Couldn't run: <reason> (the project's own test command <name>). This is about the sandbox, not about your code, so it is not counted as a problem. geo ci exits with 3 in that case. Open the check's log to read the command's full output. To get a real result, make the command work from a clean checkout (install the browser in the command, or point it at a service the sandbox has). The same word is used when most of a command's tests ran but some test files could not load for want of an optional module (a voice or GPU library): the line names the modules and how many tests could not load, and those tests are not problems. Add the extra to the command's install step to include them.

The report says the approval path was not reached#

For a Mastra app whose README describes a flow with an approver, the check follows it and reports how it ended. "The case ended as escalated and never asked for approval" means your own steps decided to hand the case to a person before an approval was needed, for the answers Geometer's stand-in gave (they are listed in the report as Geometer's choices). "Sign-in failed for the README accounts" means the README's sign-in lines are not what your app accepts when started in the sandbox; check that your app can create a local session without extra setup. The check does not invent a failure for either case; it says which step stopped the path.

Disk space and cleanup#

If the disk is nearly full, Geometer refuses in words before it starts anything, and says how much is free where it keeps its records. If a disk fills in the middle of a check, the check stops and says so. Nothing already recorded is lost.

geo gc --dry-run
geo gc

geo gc removes sandboxes, environments, networks and images that Geometer owns and that nothing is using, and clears old checks and evidence by the retention defaults: the newest 20 checks for each project, and everything behind problems you found and checks you kept. It reports the space freed, and it never removes your own containers. After a computer sleeps in the middle of a check, or a check stops because the disk filled up, run geo gc to remove leftovers.

Where the logs are#

• On a check page, the technical log is below the steps, with the exact commands.
• Open Under the hood and choose Log for the log of a check, Activity for processes, containers and network use, and Terminal for a command line in a container.
• For Geometer's state on your computer, run geo doctor.

Your records say they are from a newer version#

If you went back to an older version and see "These Geometer records were made by a newer version", nothing was opened or changed. Install the newer Geometer again, or run its installer with --rollback. If you see that another Geometer window or check is still using the records, close it and try again. See Upgrade, roll back, uninstall.

Frequently asked questions#

Does Geometer send my code anywhere?

No. Your code runs in containers on your computer. The only time text from your project leaves it is if you choose a hosted model and agree. See Privacy and security.

Do I need an account, a model or an internet connection?

You need no account and no model. You need a connection the first time, to download container images and your project's dependencies.

Does Geometer change my files?

Only when you keep a check: it writes a file under .geometer/regressions/. Opening a project and running checks do not change it.

Is "No problems found within these limits" a pass?

No. It means nothing broke in the runs that were tried. Read What was not checked.

What agents does it work with?

Agents whose tools Geometer can find and simulate, for the frameworks and protocols on Works with, each marked Supported, Partial or Not yet. The alpha has been used on sample agents, on agents written for each framework and by its own team. If your agent is not found, Geometer says what is missing.

Can I try my agent against a simulated Stripe, Shopify or Salesforce?

Yes, with geo mcp try or geo check. The simulated services are modelled on each provider's public documentation. They are not the real services, and nothing real is charged or sent. See Put Geometer in front of your MCP servers.

Can I use Guard in front of live customers' money?

Not yet. Guard is for development and staging in the alpha.

Who signs a certificate?

Your own computer, with a key it made. That shows nobody changed the file, not who issued it.

Is it free?

The alpha is free to download and use under the alpha terms, for evaluation and for internal work, including in CI.

Does it work on Windows or an Intel Mac?

Not in the alpha. See Alpha limits.

Report a problem#

Open an issue on GitHub: the issue chooser. In the app, Help, then Report a problem, opens the same page in your browser. Say which version, which platform and what kind of project you used, what you did, what you expected and what happened. Do not paste secrets, customer data or private code you cannot share; describe it instead. For a security problem, use private reporting instead; see Privacy and security.

• Alpha limitsWhat the alpha does not do yet.