Skip to main content

​
Start with the connection

When a workflow step fails against an external app, the connection is one of the first things to check. Even if the workflow logic is correct, a bad connection can still cause the run to fail.

​
Most common connection problems

The most common causes are:
  • the wrong account is connected
  • the step is using the wrong saved connection
  • the connection no longer has the required permissions
  • the token or credentials have become invalid
  • the account credentials, such as the password, were changed and the token was revoked
  • a default connection was selected when a different account was intended
These issues are much more common than a broken integration in the abstract.

​
Signs that the connection may be the problem

Look at the failing step and ask:
  • did this workflow used to work before
  • does the failure mention auth, access, or invalid credentials
  • is the selected app account still correct
  • did someone change permissions or rotate credentials recently
  • did the account password or other credentials change recently
If the answer to any of these is yes, the connection is a strong suspect.

​
A practical debugging order

Use this sequence:
  1. Confirm which connection the failing step is using.
  2. Confirm that the connection belongs to the intended account.
  3. Check whether the account still has the right permissions.
  4. Reauthenticate or replace the connection if it appears invalid.
  5. Run a test again before changing workflow logic.
This order helps avoid unnecessary workflow edits when the real issue is simply app access.

​
Check for invalid state

Workflow Machine can surface when a saved connection is invalid. If you see a connection marked invalid, treat that as a strong signal that the problem is with the app access itself rather than the workflow design. In that case, the best next step is usually to reconnect, refresh, or replace the connection and then rerun the workflow test.

​
When the wrong account is the problem

Sometimes the connection is technically valid, but it is still wrong for the workflow. Examples:
  • a personal Slack workspace instead of the company one
  • a test Notion workspace instead of production
  • an old Gmail account instead of the current inbox
This is why account verification matters just as much as authentication success.

​
When permissions are the problem

A connection may succeed during setup but still fail during execution if the account lacks the permissions needed for a specific step. For example, the workflow might be able to sign in but not:
  • post to the target channel
  • edit the destination page
  • create the requested record
  • access the document or database you selected
If a step fails only for certain targets, permissions are often the cause.

​
After you fix the connection

Once you update or replace a connection:
  • rerun a test
  • verify the specific failing step
  • trigger one real run if the workflow is important
That confirms the problem is actually resolved and not just temporarily masked.

​
Keep troubleshooting focused

When a workflow fails, it is tempting to edit several things at once. Try not to. If the real problem is the connection, changing workflow logic at the same time makes debugging slower. Fix access first, retest, then move on only if the issue remains.