Troubleshooting

Sorted by how often each one comes up.

Upload and processing

Processing failed

Open the failure details on the file. You get a reference code, the source format we detected, and a button to download your original, which is still there and untouched.

The usual causes:

• The format is not supported. Check the list in Concepts. GeoPackage is a common surprise: vector layers work, raster tiles inside a GeoPackage do not.
• No coordinate system. DXF and some CSV exports carry no projection information. Give an EPSG code at upload.
• A shapefile is missing a part. Selecting only the .shp will not work. You need .shx and .dbf too, plus .prj for the projection.
• The file is over 10 GB. Cloud optimization stops there. Optimize on your own machine and upload the result, as described in File optimization.

If none of those fit, use Send crash report on the failure screen. It attaches the technical detail automatically, so add a line about what you were trying to do and send it.

Processing is taking a long time

Most files finish in a few minutes. Large rasters and dense vector layers take longer, and the file row shows which step it is on.

If it has not moved in a while, refresh once before assuming it is stuck.

The upload was rejected before it started

Usually storage. If your organization is at its included storage and overage is off, new uploads are blocked rather than billed. Check Profile → Billing, and either free some space or enable overage.

Maps

A layer is missing from a published map

Almost always because the layer is still private. Map access and file access are separate settings, and both have to be public for a visitor to see the layer.

Open the map in a private browser window. What you see there is what a visitor sees, and it is the fastest way to catch this.

A map still lists a file I already deleted

Maps keep a copy of their layer list. Deleting the file from Files does not pull it off the map. Open the map in the builder: those rows are labelled (not in Files). Remove them there, or restore the files if you still want them on the map, then save.

The map opens in the wrong place

That is the map's saved default view, not a bug in the viewer. Set it in the map builder with Use current view as initial, and set zoom limits and pan bounds while you are there.

A styled layer draws as one flat colour

You chose an attribute for a categorized style but never pressed Classify. Picking the attribute does not assign colours by itself. Press Classify, or run sarkoa map layer classify, or call classify_vector_style from MCP.

Classify says it needs field samples

Sarkoa needs to know what values are actually in the file before it can build classes. That information is written during processing, so a file that failed or is still running has none yet. Wait for processing to finish, and reprocess the file if it completed a long time ago.

A raster offers the wrong controls

If a single-band elevation model gives you band selection instead of a colour ramp, it was sorted as visual imagery instead of measurement values. Open Processing details on the file and switch it. See File optimization.

Colours changed after switching a raster's kind

Expected. A colour ramp and an RGB band mapping are not interchangeable, so switching resets that file's saved style. Maps already using the layer keep their own copy.

Two people edited a map and one change vanished

It did not vanish; the second save was rejected. Maps carry a revision number and the server refuses a save based on a stale one. Reload and reapply. From the CLI and MCP, pass --expected-revision or expected_revision.

Embeds

The embed is a thin strip

No height on the iframe. See Embeds.

The embed is blank

Map access is still set to organization. Set it to public.

It works for you and not for anyone else

You are signed in. Check it in a private window.

Sharing

The person I shared with cannot see the file

Which mechanism did you use?

• Email invite needs them to have a Sarkoa account on that exact address.
• Share link works for anyone with the URL, but stops working if the link was recreated. Changing an existing link's settings creates a new one and invalidates the old.
• Making a file public does not send anything. It permits the file to appear on public maps; it does not create a URL.

Full breakdown in Sharing and access.

A shared file is not in my Files list yet

Cross-organization shares only appear at the top level of your Files page, not inside folders, and only after the file finishes processing.

API, CLI, and agents

403 with plan_upgrade_required

The public API needs Essential or above. Keys for the CLI, QGIS, and MCP are separate and work on any plan.

429 Too Many Requests

You hit a rate limit. Wait the number of seconds in the Retry-After header. Completing an upload is capped at 30 per 10 minutes per key, so for a bulk backfill, pace to roughly one every 20 seconds.

If the requests you are burning are status checks, stop polling and register a webhook instead. That removes the loop rather than slowing it down.

401 on a key I know is valid

Probably the wrong kind of key for that host. Asset API keys work on api.sarkoa.com; Profile keys work on the app host. API reference has the split.

A feature query returns 413 or 415

Feature query reads your original upload, so it needs a GeoJSON FeatureCollection under 32 MB. The reason field says which rule you hit. Feature query → Limits lists all three.

The CLI cannot find my file

References can be a name, a short ref, or a full ID. sarkoa list without --folder only shows the library root, so pass --folder if the file is nested.

An agent invented a URL that does not work

Agents should use the links the tools return rather than constructing them. If yours is guessing, the Skills pack teaches the right habits, and MCP lists them.

A new MCP tool is not showing up

Reload the MCP connection in your AI app.

Still stuck

Email support@sarkoa.com with your organization name, the file or map, roughly when it happened, and the reference code if you have one. Support and contact has the full list.

If several things are failing at once, check status.sarkoa.com first.