Skip to Content
Using metamorphOSIntegrationsTroubleshooting

Troubleshooting

Symptom, cause, and fix for the problems you’re most likely to hit when building and running integrations. For the full walkthroughs, see Building Custom Connectors, Authentication & Credentials, Inbound Webhooks, and Marketplace Integrations.

When a process step fails, open the instance in Monitor

  • the failing step’s message tells you which of the cases below you hit.

The connector

It still says Draft. A saved connector isn’t usable until it’s published. Open it and click Deploy.

Its functions don’t appear in the Builder. Only deployed connectors offer their API Calls and webhooks as steps. Deploy it, then reopen the step picker.

Connecting an account

The account shows needs sign-in or Error. It has no working secret yet, or the last attempt failed. Re-enter the secret (or Re-authenticate for OAuth) from the Credentials panel.

OAuth - the provider shows a redirect-URI error at the consent screen. The Callback URL shown in the OAuth client form isn’t registered at the provider, or doesn’t match exactly. Copy it from the form and add it verbatim to your provider app’s allowed redirect URIs - no extra slash, no typo.

Note

For a managed marketplace connector, the publisher operates the provider app, so the publisher - not you - registers the callback. If a managed connector fails at consent with a redirect-URI error, it’s the publisher’s to fix.

OAuth - the popup says the request expired or is invalid. A consent link is single-use and time-limited. If you took too long or reused the link, just click Connect again to start a fresh consent.

Calls keep working, then suddenly fail. Usually the OAuth grant ended - the user revoked the app at the provider, or the account was disconnected. The account shows it’s no longer authorized; Re-authenticate it. (Token refresh itself is automatic; you don’t manage it.)

A step that calls a connector fails

“The connector isn’t authenticated.” The account the step uses has no working secret. Connect it on the Credentials panel.

“No account selected.” The step doesn’t name an account and the connector has no default. Set a default on the Credentials panel (or pin an account on the step).

“That account doesn’t exist.” The step names an account that was deleted or renamed - including a value passed in at start time. Use an existing account, or recreate the missing one. There’s deliberately no fallback to the default.

The call goes to a URL containing a literal ${…}. The connector declares a connector parameter (like ${shop}) that the selected account doesn’t fill. Set that account’s parameter values from its menu (Edit parameter values). Values are per-account - adding a second account means filling its values too.

The provider rejected the call. The step shows the provider’s own error message. Check the inputs you wired to the endpoint against what the provider expects. If a call returns a normal response that the provider nonetheless treats as a failure, the connector’s success condition is doing its job - read the message and fix the request.

Webhook deliveries don’t arrive

The symptom is always the same: the provider’s delivery log shows the delivery was rejected, and no process instance starts. metamorphOS rejects anything it can’t verify, and on purpose tells the provider nothing about why - so work through the causes, most common first:

  1. No signing secret. A webhook with no signing secret set on any account can’t be verified, so deliveries are rejected. Set it on the Credentials panel.
  2. Secret set after deploy. The process captured the verification settings when it was deployed. Set the secret first, or redeploy the process after changing it.
  3. The two secrets differ. The value at the provider and the value in metamorphOS must be identical - watch for stray spaces or a trailing newline from copy-paste.
  4. Wrong header, prefix, or encoding. The Inbound authentication settings must match how the provider actually signs: the right header name, the right value prefix (e.g. sha256=), and the right algorithm/encoding. Compare a sample delivery header against your settings.
  5. The body was altered in transit. A proxy that re-formats the payload (key order, whitespace, line endings) breaks the signature. Deliver the provider’s bytes untouched.
  6. Timestamp outside the window. With replay protection on, a delivery whose timestamp is too old is rejected even with a valid signature. Check clock skew and that the timestamp unit (seconds vs milliseconds) matches the provider.
  7. Just rotated the secret. The new value works immediately, but a brief cache may let the old one verify for a few minutes; deliveries signed with the old secret after that fail. For zero-gap rotation, stage the new secret on a second account first (see Rotating the secret).
Tip

A delivery that succeeds but starts no process is a different problem from one that’s rejected. If the provider’s log shows success but nothing runs, the delivery was verified - check the webhook’s matching conditions and that a process is actually subscribed.

Marketplace

“Already installed.” Re-activation is refused so your accounts and connections are never silently overwritten. Remove the connector first, then activate again and re-connect its accounts.

“Managed OAuth isn’t available.” The publisher ships no managed app for this connector - connect with your own provider app instead (the Setup guide covers registering it).

Best practices

The habits that prevent most of the above are collected in Authentication & Credentials → Best practices: one account per environment, least-privilege scopes, point the default at the safe account, rotate by re-submitting, and set webhook secrets before deploying.

Last updated on
Using Integrations in ProcessesMonitor