How to Handle Map Server Errors: Fix the Inputs, Ask the User or Hand Off

Key Takeaways

• The task today: You want a geology agent that works through scanned geologic maps on its own, with Stratigraphic Amenity, an open-source server whose map tools AI agents call (an MCP server), doing the map work.
• The problem: Every tool fails sometimes, whether a package is missing, bounds are out of range or a file is too large. Most tools report it in a message written for a person, which leaves an agent guessing what to do next.
• What the tool does: Stratigraphic Amenity handles errors for the agent. Every failed call comes back with an error code it can act on, a plain message, a trace ID and, where the next step depends on the setup, recovery hints. The agent fixes what it can, asks you before installing anything and passes the rest on with the trace ID, so an error is a next step for the agent, not a problem for you.

TL;DR

Building a geology agent that works through scanned maps on its own? Every tool fails sometimes, and Stratigraphic Amenity, an open-source server whose tools AI agents call for scanned geologic maps (an MCP server), has great error handling: each failed call comes back with an error code the agent can act on, a plain message, a trace ID and, where the next step depends on the setup, recovery hints. The agent fixes what it can, asks you before installing anything and passes the rest to whoever runs the server with the trace ID, so an error becomes a next step for the agent rather than a problem for you.

What Should a Geology AI Agent Do When a Tool Fails?

A geology AI agent is halfway through a scanned geologic map when the layout detector refuses to run. What comes back is precise. The code is missing_extra, the cause names a missing Python module, and the message lists the requirements still outstanding. The agent has a shell, and the fix looks like one line.

It is the wrong line, and the server says so before the agent can type it. Stratigraphic Amenity, our open-source MCP server for scanned geologic maps, attaches recovery hints to this error. One reads: “Do not run installer commands in your own shell. It is a different environment from the server, so its PATH may lack the command and anything it installs lands in the wrong data root.” Another closes the door: “Requirements that are Python packages cannot be installed by any tool here; report those to the operator.”

That exchange holds the whole topic. For an agent working with geology tools, the useful question about a failure is not “what went wrong?” but “who can fix this from here?” Most of the time, the answer is someone other than the agent.

Errors Written for a Person

Every GIS tool fails sometimes: a file will not open, a package is missing, a value is out of range. GIS analysts grew up with errors written for a person. Anyone who has run GDAL from a terminal has seen ERROR 4: and ERROR 1:. The figure is GDAL’s error number: 4 means a file failed to open, and 1 means “application defined”, a number that a great many messages share. The number tells you little and the sentence after it tells you everything. That works because the reader is you. You recognise the cause, and when the fix is not yours, you know whom to call.

An agent reads differently. It takes a sentence literally, it rarely knows whom to call, and it often has tools within reach that a person at a desktop would never point at a server’s environment. So Stratigraphic Amenity splits every failed tool call into parts for different readers. The error envelope, geomap-error/v1, always carries a stable code to branch on, a message for people and a trace_id. It may add details, a cause limited to a few allowlisted identifiers, and recovery_hints. The rule the README gives agents is short: branch on the code, follow the hints, keep the trace ID.

Sorting Error Codes by Who Can Act

Sort the server’s error codes by who can act on each, and the agent’s own column is short. It can correct its arguments (invalid_arguments) and its bounds, CRS or control points (invalid_bounds). Before asking a question that needs an area, it can georeference first (georef_required). It can register a map again when the server no longer knows a map ID or resource link (artifact_not_found). After unknown_tool it can refresh its tool list, unless the missing tool is one the operator withheld. Under unknown_provider, a misspelt provider name, named providers that cannot serve this kind of request and malformed provider_options are the agent’s to fix as well.

What a Geology AI Agent Leaves to the User and Operator

The next column needs a person’s consent. Missing detector weights and a missing knowledge base can be installed from the client, through geomap_prepare_detectors and geomap_prepare_knowledge. Both download files and write to disk, so the hints tell the agent to confirm with the user first. Two codes are shared work. For a file in the wrong format (unsupported_media) or over a size limit (oversize_image), the agent can switch to a supported image, a JSON bundle or a smaller derived file. Otherwise the user supplies another file, or the operator raises the limit.

Most of the rest belongs to whoever runs the server: a map outside the allowed roots, a corrupt registry, custom asset paths the installer will not touch, an install that failed, a missing Python package, a server bug. One code, preparation_disabled, never reaches an MCP agent at all. A preparation tool the operator withholds leaves the tool list, so a call to it returns unknown_tool. On a laptop the user and the operator are often the same person. The roles still differ, because the operator’s fixes happen in the server’s environment, not in the agent’s.

Why Geology AI Recovery Is Mostly Routing

So recovery, for a geology AI agent, is mostly routing. Retrying the same call is rarely part of it. The agent guide allows one retry, for internal_error, and only if it is safe. Several tools are not idempotent: every georeference against a registered map writes a new revision, and every knowledge query writes a new bundle, so a blind loop leaves records behind. The retry belongs after the fix. Once the knowledge base is installed, the server’s own summary says to retry earlier requests to the providers that are now ready.

The Hint Knows the Server

The routing cannot live in a fixed table in the agent’s prompt, and the code shows why. The same failure needs a different route on a different server. When the detector is not ready, the server checks whether its operator kept geomap_prepare_detectors exposed. If so, the first hint says to call it after the user confirms. If not, the hint tells the agent to ask the operator, and quotes the installer command to run in the server’s environment. A table copied into a prompt cannot know which server it is talking to. The server computes the hint at the moment of failure, from its own settings.

Act on the Response, Not a Copied Table

A copied table has a second weakness: it holds only the codes its copier knew about. The hint arrives inside the response, written by the server for the case at hand. A lookup whose named providers need a knowledge asset that is not installed returns missing_knowledge_asset, and its hints say exactly what to do. An agent that acts on the response can handle a code its prompt has never seen; one that routes on a copied table cannot.

The Trace ID Travels With the Handoff

A handoff needs something to hand over. Geologists solved this long ago with the sample ticket. One number goes in the bag and the same number on the logging sheet, and the assay certificate comes back weeks later keyed to it. A bag without a ticket is just rock.

The trace_id plays that part. It is a random 32-character hex string, one per tool call and shared by any nested calls, and the server stamps it on every error that leaves without one. It then writes the ID into two records that otherwise never meet. The agent gets it in the envelope, beside the message and hints. The operator gets it in a one-line log record on the server’s standard error, with the tool name, the outcome code and the duration. That line leaves the message out by design, and after an unexpected exception the full traceback sits just above it. Neither half explains a failure alone. An agent that reports “map processing failed” without the ID has handed over a bag with no ticket.

The Limits of the Geology AI Handoff

A few cases need the agent’s own attention, and each has a simple check:

• Codes without hints. invalid_bounds and unknown_provider carry no recovery hints, so the agent reads the message. Under unknown_provider, the message tells a misspelt name, a provider that cannot serve the request and malformed provider_options apart from a provider that failed at runtime, which is usually the operator’s to fix.
• Warnings on a successful result. When a call names no provider, or another named provider succeeds, a failing provider shows up as a warning on the result rather than as an error. Read the warnings on every result, not only the errors.
• A registry that will not load. If the registry file is not valid JSON, the server stops at startup, before any tool call can return an error. Check that the server starts before looking for a tool error.
• The server log. The trace ID reaches the operator’s log at the default INFO level. Keep the log there, so every ticket has a matching line.

What the Agent Still Owes the Operator

When the agent cannot fix a failure, its last duty is a short report: what was not checked and why, who can fix it, and the ticket number. A field assistant does the same with a broken instrument. For a geology AI agent, that report is most of what recovery means.

A report like that is only as good as what the server hands the agent to put in it. The agent should not have to invent the route, and nobody should have to maintain a table of remedies for every deployment. The open-source server builds the route into the error itself, and you can watch it change by flipping one setting on your own machine.

The decision about who should act is small enough to read in full. It is not made in the documentation or in the agent’s prompt. It is made in a few lines of the adapter, at the moment the detector fails, by asking how this particular server was configured.

Where the Hint Learns Which Server It Is

One function computes the route in the opening example: _detector_not_ready, which turns a detector failure into the error an agent sees.

        if detector_preparation_enabled():
            hints = [
                "Call `geomap_prepare_detectors` to install the approved runtime and weights "
                "into the server's data root. Confirm with the user first: it downloads about "
                "200 MiB and writes to disk.",
            ]
        else:
            hints = [
                "Ask the server operator to run `stratigraphic-amenity-assets --all "
                '--root "$GEOMAP_DATA_ROOT"` in the server environment, or to re-expose '
                "`geomap_prepare_detectors`.",
            ]
        hints.append(
            "Do not run installer commands in your own shell. It is a different environment "
            "from the server, so its PATH may lack the command and anything it installs lands "
            "in the wrong data root."
        )
        if any("missing" in item and "module" not in item for item in missing):
            hints.append(
                "Requirements that are Python packages cannot be installed by any tool here; "
                "report those to the operator."
            )

detector_preparation_enabled() reads GEOMAP_MCP_ENABLE_DETECTOR_PREPARATION at the moment of failure (mcp/adapter.py:853-863). Left unset, the preparation tool stays exposed and the first hint points to it. Set to false, the tool disappears and the first hint turns toward the operator. The prohibition goes in either way. The third hint appears only when the outstanding list names a missing package or shared library, such as “cpuinfo is missing”.

Where the Detector’s Own Message Goes

The detector’s own exception still says “Run stratigraphic-amenity-assets peace-yolov10-runtime.” The adapter keeps that text in details.detector_error, scrubbed of paths, but puts the route in recovery_hints. It also repeats the remedy and the full requirement list in the message, because, in the code’s own words, “a host may surface only message” (mcp/adapter.py:260-261). A separate function, error_result, assembles the envelope itself (mcp/server.py:84-127). It generates a trace_id when the failure has none, and appends the code, the ID and each hint to the text the agent reads.

Watching Geology AI Error Routing Change on Your Machine

To watch the routing change, clone the Stratigraphic Amenity repository and install the full profile:

uv sync --group dev --extra mcp --extra geo --extra assets --extra detectors

Register the server with your MCP host, but don’t install the detector assets yet. Register a map from an allowed root, then call geomap_process_image:

{"map_id": "<map-id>"}

On a fresh install the call returns isError: true with code missing_extra. details.missing_requirements names the runtime and both sets of detector weights, details.detector_error holds the detector’s own message, and recovery_hints holds the first two hints above. The text content ends with an “Evidence digest” block: error.code, trace_id, details and one recovery_hint line per hint. With the default log level, the server’s stderr gets an event=tool_call line with the same trace_id and outcome=missing_extra.

Now add GEOMAP_MCP_ENABLE_DETECTOR_PREPARATION=false to the host’s env block and restart. The same call now routes the agent to the operator, and geomap_prepare_detectors is gone from the tool list.

FAQs

Should a geology AI agent retry a failed tool call?

Rarely as a first move. The agent guide allows one retry, for internal_error, and only if it is safe. Several tools are not idempotent: each georeference against a registered map writes a new revision, and each knowledge query writes a new bundle. Retry after the fix instead, for example once the knowledge base is installed.

What is the trace_id in a Stratigraphic Amenity error?

It is a random 32-character hex string, one per tool call and shared by nested calls. The agent gets it in the error envelope. At the default log level, the server also writes it to a stderr line with the tool name, the outcome code and the duration, but not the message. Matching the two halves explains the failure.

Why shouldn’t an AI agent install missing packages from its own shell?

The agent’s shell is a different environment from the server’s. Its PATH may lack the installer, and anything it installs lands in the wrong data root. Detector weights and the knowledge base come through the server’s own preparation tools after the user agrees. Missing Python packages go to the server operator, because no tool on the server can install them.

Which error codes can a geology AI agent fix by itself?

Mostly its own inputs: invalid_arguments, invalid_bounds and georef_required, plus artifact_not_found when the server no longer knows a map ID, unknown_tool unless the operator withheld the tool, and unknown_provider when a provider name or option is wrong. Wrong formats and oversized files are shared work. Missing assets need the user’s consent; missing packages need the operator.

Try It With Geocluster

Stratigraphic Amenity is one of the Geocluster tools, MCP servers that let AI agents work with geology data and maps.

Before an agent meets any of these errors, it can check what the map server can do and see which tools are ready.