McPherson AI
Observa help · Troubleshooting

What went wrong, and the safe way out of it.

Every refusal prints REFUSED <CODE>. Find the code here first. Two rules run through the whole page: run observa diagnose before you change anything, and never hand-delete credentials, config or state when a supported command covers it.

SHADOW_ONLY · AUTHORITY NONE · ENFORCEMENT OFF — Observa observes and reports. It has no authority to allow, deny, approve, block, retry, or change anything in your systems.

Start here

The four read-only commands, in order

observa status      # what is installed, what is paired
observa diagnose    # integrity, signature, config presence, permissions
observa activity    # recent local observations
observa decisions   # local counterfactual records only

None of them writes anything or probes the network. observa diagnose exits 1 if any check FAILs, and its output is paste-safe: it reports key presence and shape, never a config value, credential or pairing code. It is the right thing to attach to a support request.

observa agents and observa agent <id> on the n8n path always return an explicit limitation rather than a list. That is a stated boundary, not a fault to troubleshoot.

Common failures

Ten cases

1An existing credential requires --replace-existing

Symptom
Pairing preflight refused: EXISTING_CREDENTIAL_REQUIRES_REPLACE_FLAG, before any code is read. OpenClaw connector only.
Likely cause
The selected OpenClaw profile already holds a connector credential, and the tool will not silently replace a working one.
Safe diagnostic
observa pair --api-url <https://host> --profile default --replace-existing --preflight-only
Reports profile, install layout, version, enabled state and credential presence without reading a pairing code.
Safe recovery
Confirm the endpoint you are migrating to is the one you intend, then re-run without --preflight-only. The prior config and credential are written to an owner-only rollback snapshot first — see where that snapshot lives and how to restore it.
Do not retry when
The endpoint in the command is not the one you meant. Replacing against the wrong endpoint is the mistake the flag exists to prevent.
Contact support if
Preflight keeps refusing after you pass --replace-existing, or the rollback snapshot directory is missing.

2The access request is pending, or the verification code expired

Symptom
observa request-status shows EMAIL_PENDING or PENDING_REVIEW; or verifying refuses with ACCESS_REFUSED / ACCESS_CODE_INVALID.
Likely cause
PENDING_REVIEW is a human queue — that is the system working. ACCESS_REFUSED on a code usually means the 10-minute window passed, the code was already used, or a digit is wrong.
Safe diagnostic
observa request-status
Safe recovery
In PENDING_REVIEW: wait. In EMAIL_PENDING with an expired code: observa request-access --resend, waiting at least 60 seconds between sends. After EXPIRED: observa request-access --new --api-url <https://host>.
Do not retry when
You are in PENDING_REVIEW. Resubmitting does not speed up review, and a second request for the same address will be refused. Also stop after the third send — that is the hard maximum, and failed verification attempts are retained, with the fifth ending the request.
Contact support if
You are approved but no invitation arrived after --resend, or the state does not match the documented lifetimes.

3The pairing code expired or was already used

Symptom
REFUSED PAIR_REFUSED, often with a bounded reason from the pairing lane.
Likely cause
Codes live 10 minutes, are single-use, and are bound to one organization and workspace. Unknown, expired, already-spent and wrong-tenant codes all give the same answer on purpose, so the refusal cannot be used to probe.
Safe diagnostic
observa status
Confirms whether anything is paired yet.
Safe recovery
Create a fresh pairing code in Hosted Observa and run observa pair --base-url <https://host> --code-stdin again, promptly.
Do not retry when
A fresh code just failed. Minting more will not help and each one is a live secret. Also never pass a code as an argument to get around a paste problem — that refuses, and the code should then be treated as exposed.
Contact support if
Two consecutive fresh codes fail, or you suspect the code was issued in the wrong workspace.

4Observa cannot reach the Hosted endpoint

Symptom
REFUSED PAIR_HOSTED_UNREACHABLE, REFUSED MANIFEST_FETCH_UNREACHABLE, or REFUSED ACCESS_UNAVAILABLE.
Likely cause
DNS, network path, TLS, or the service being down. Access commands also refuse outright if TLS verification has been disabled in your environment (ACCESS_TLS_REQUIRED).
Safe diagnostic
observa diagnose
hosted_connectivity is reported as INFO — Observa deliberately does not probe your network for you. Check reachability with your own tools.
Safe recovery
Fix the network path, then re-run the same command. Nothing was consumed: a failed connection does not redeem a pairing code and does not change local state. If NODE_TLS_REJECT_UNAUTHORIZED is set in your environment, remove it — do not work around the check.
Do not retry when
You cannot reach the service at all. Repeating a network-failing command is noise, not diagnosis.
Contact support if
The endpoint is reachable from a browser on the same machine but the CLI still refuses.

5The installation is paired but no recent activity appears

Symptom
observa status shows installed and hosted configured, but observa activity returns an empty list.
Likely cause
Most often the runtime is simply idle, or the observer is not running, or the runtime hook environment was never loaded. An idle runtime producing nothing is normal, not a fault.
Safe diagnostic
observa status
observa diagnose
observa activity
service_state in diagnose tells you whether the observer is running.
Safe recovery
If the service is stopped, observa start. If it is running, exercise a real workflow and check again. Confirm your runtime actually loaded the environment file observa n8n-setup printed.
Do not retry when
Nothing has run in the runtime yet. Restarting Observa repeatedly will not manufacture evidence, and an empty view is an honest one.
Contact support if
A workflow demonstrably completed, the observer was running, the hook environment was loaded, and nothing appeared.

6n8n is installed but no runtime evidence appears

Symptom
n8n runs workflows normally; observa activity stays empty.
Likely cause
Almost always the hook environment was not loaded by the n8n process. observa n8n-setup writes the file and prints its path — it does not restart or reconfigure n8n, by design.
Safe diagnostic
observa diagnose
Check config_present:n8n_loopback_credential and config_permissions.
Safe recovery
Set the loopback credential if absent (observa config set n8n_loopback_credential '<24+ characters>'), re-run observa n8n-setup, then configure your own n8n service or container to load the printed environment file before n8n starts, and restart n8n yourself.
Do not retry when
You have not yet confirmed that the n8n process has that environment loaded. Do not add an Observa node to a workflow — the hook observes ordinary workflows automatically and workflow edits are not the fix.
Contact support if
The environment is demonstrably loaded by the n8n process, the observer is running, diagnose passes, and evidence still does not appear.

7OpenClaw is installed but no runtime evidence appears

Symptom
The connector is paired, agents run, and no evidence shows up.
Likely cause
The connector reports only when a supported tool hook actually fires. Attempt receipts, lifecycle records and heartbeat are not meaningful activity, and Codex-native tools appear only when the OpenClaw host relays them through its supported tool-hook contract.
Safe diagnostic
observa status
observa activity
status distinguishes plugin installation metadata, plugin configuration, pairing, enabled intent and observing evidence. Pairing is never reported as a live Hosted connection.
Safe recovery
Confirm the plugin is enabled and loaded (observa enable if its durable disable control is set; a gateway reload may be required and the command says so). Then run ordinary agent activity that uses a tool.
Do not retry when
The agent has not used a tool. Also do not treat a quiet view as a connector failure — CONFIGURED with no completion in the inspected window is a truthful state.
Contact support if
A tool demonstrably completed through a supported hook and nothing was recorded.

8Signed manifest or composition verification fails

Symptom
REFUSED SIGNATURE_INVALID, SIGNING_KEY_UNTRUSTED, MANIFEST_TENANT_BINDING_MISMATCH, MANIFEST_INSTALLATION_BINDING_MISMATCH, ARTIFACT_DIGEST_MISMATCH, ARTIFACT_CONTENT_DIGEST_MISMATCH or CLI_VERSION_BELOW_MANIFEST_MINIMUM.
Likely cause
The manifest was not signed by a trusted key, was issued for a different tenant or installation, or an artifact on disk does not match the digest the manifest pins. It can also mean your CLI is older than the manifest requires.
Safe diagnostic
observa diagnose
manifest_signature, package_integrity and component_versions_match_manifest localise it.
Safe recovery
For CLI_VERSION_BELOW_MANIFEST_MINIMUM, upgrade the CLI. For a digest mismatch, re-run observa install so artifacts are re-resolved by their pinned SHA-256. Nothing was composed: these refusals happen before any byte is staged.
Do not retry when
Never. Do not try to bypass a verification refusal, hand-place an artifact, point --artifacts at an unofficial directory, or edit a manifest. A verification failure is the system doing its job; treat it as a security event until explained.
Contact support if
Immediately, for any signature, key-trust or tenant-binding refusal. Send the refusal code and observa diagnose output.

9The credential was revoked, or re-pairing is required

Symptom
REFUSED INSTALLATION_REVOKED, or observa diagnose shows revocation FAIL with a reason code. Hosted delivery stops.
Likely cause
A signed revocation for this installation was issued and verified locally, or the delivery credential was revoked server-side.
Safe diagnostic
observa diagnose
The revocation check names the reason code. Its output contains no secrets.
Safe recovery
A revocation is a deliberate decision, so start by finding out why. If you are expected to reconnect, re-pair: after an observa unpair the installed identity is retained and observa pair with no flags mints a replacement credential. If you were issued a new pairing code, use the --base-url … --code-stdin form.
Do not retry when
Do not delete the config file, the credential or state.json by hand to “reset” things. unpair, rollback and uninstall --purge-config are the supported paths, and hand-editing loses the recovery state those paths depend on.
Contact support if
You did not expect the revocation, or you cannot determine why it was issued.

10An update or rollback will not complete

Symptom
REFUSED NOT_INSTALLED, MANIFEST_NOT_NEWER_THAN_CURRENT, ROLLBACK_TARGET_ABSENT or ROLLBACK_MANIFEST_BINDING_MISMATCH.
Likely cause
update requires an existing installation and a strictly newer manifest. rollback requires a retained previous release — and it is single-depth, so after one rollback there is nothing further to go back to.
Safe diagnostic
observa status
observa diagnose
status prints the current and previous manifest ids.
Safe recovery
Install the correct newer manifest, or accept that there is no earlier release to return to and re-install the intended one with observa install --manifest <signed.json>. A failed update leaves the existing installation intact, and if a retained release fails integrity, rollback rebuilds it offline from the verified artifact cache.
Do not retry when
You are trying to reach an older release that was never retained. Repeating rollback cannot create one, and neither can editing state.json.
Contact support if
ROLLBACK_MANIFEST_BINDING_MISMATCH appears — the retained manifest does not bind to this installation, which should not happen.
Recovery and rollback

The supported way back, and exactly what each step keeps

Work down this list. Each step is reversible until the last one.

StepWhat it doesWhat survives
observa stopStops Observa’s own observer. Never touches your n8n. Everything. Installation, pairing and evidence are untouched.
observa diagnoseRead-only. Localises the problem before you change state. Everything.
observa update --manifest <newer.json> Moves forward to a strictly newer signed manifest. The previous release is retained for one rollback. A failed update leaves the current installation intact.
observa rollbackReturns to the retained previous signed manifest, fully offline. Installation identity, pairing and local config. Single-depth: afterwards there is no further previous release.
observa unpairRevokes Hosted delivery for this installation. The installed identity is retained. A recovery URL and the installation secret are kept locally so observa pair with no flags can re-pair without a new code.
observa pair (no flags)Re-pairs the retained identity. The same installation. No pairing code is redeemed and no new installation is created.
observa uninstall --yes Stops the service and removes releases, artifacts, manifests and state.json. Your local config survives. Hosted credentials are not revoked — run unpair first if you want that.
observa uninstall --yes --purge-config The same, and removes your local config too. Nothing local. This is the irreversible one; the loopback credential and any pairing recovery state go with it.

Reinstalling. After uninstall without --purge-config, your pairing config is still present, so observa install can retrieve and verify the issued manifest again. After --purge-config you need a fresh pairing code and must start from observa pair --base-url … --code-stdin.

On the OpenClaw connector, uninstall runs the OpenClaw plugin uninstaller in the selected profile, preserves receipts, and does not revoke credentials — unpair first. A pairing that used --replace-existing can be restored exactly with --rollback pair_<uuid>; see the pairing page.

Still stuck

Getting help.

How to report it, and what never to include → Check the exact syntax → Access and pairing lifecycle → What the output means →
Contact supportCheck the syntax