obto-troubleshooting

OBTO Troubleshooting

Read the envelope first

OBTO tools return structured errors: {ok:false, error:<code>, hint:<what to do>}. The hint is authoritative — follow it before improvising. An "error" string inside an ok:true payload is NOT a failure.

Common errors and what they actually mean

-32602 missing appName/domain — the stateless contract: every call carries both explicitly. Get domain from obto_whoami; ask the user which app.

cross_tenant_not_allowed — the call passed a domain other than the signed-in identity's own, and the identity is not a super-user. Only super-users (dev-domain identity) may address other tenants. Use the identity's own domain, or have an operator run the call.

unknown_domain (3.5.26) — a super-user call named a domain that is not an ACTIVE tenant in the pltf_domain registry. Almost always a typo'd slug: the envelope's didYouMean lists close matches, and whoami's tenantDomains carries the registry summary. Platform-code domains (dev, global, mcp, core, edu) are exempt. If the tenant was provisioned seconds ago, retry once — misses re-read the live registry.

collection_not_in_allowlist — obto_db_query only reads platform collections (pltf_log, pltf_appmap) plus collections the app opted into via exposedCollections on its application record. Fixes, in order: pick a collection from obto_db_list_collections; read business data through the app's own API routes via obto_invoke_route (often the more correct pattern); have the app owner add the opt-in with obto_db_set_exposed_collections (3.5.17+). Super-users (dev domain) bypass the allowlist automatically on 3.5.17+ (logged); on older servers they pass allowUnexposed: true explicitly.

Query returns 0 rows you know exist — the injected tenancy filter doesn't match how documents are scoped (e.g. docs lack an app or domain field). Run obto_db_describe_collection and check the collection's tenancyFields.