Welcome to Next Matter home pagelight logodark logo
  • Contact us
  • Status
  • Sign in
  • Sign in
Get started
Components
Integrations
Portals
Sidebars
Solutions
Updates
APIs
  • Product updates
  • Videos
    • Overview
    • Welcome
    • Product automation
    Build
    • Get started: Build workflows
    • Integrate across tools
    • Visual builder
    • Notes in workflow
    • Branch your workflows
    • Troubleshooting workflows
    Organize
    • Inbox
    • My requests
    • Datasets
    Run
    • Get started: Work with tasks
    • Manage workflows/instances
    • Reassign tasks
    • Complete steps
    • Participate in workflows
    • Create external workflows
    • Complete tasks as guest
    Report
    • Export data
    • Search
    • Monitor data
    • Stages board
    • Monitor progress with roadmap
    Manage your account
    • Personal profile
    • Reset your password
    • Troubleshoot login
    Manage workspace
    • Users and teams
    • Security and SSO
    • Custom branding
    • Company dashboard
    Build

    Troubleshooting workflows

    Refer to this page if you’ve run into issues creating or starting a workflow.

    How to debug failed integration steps from email data

    The email notification provides an admin or a tech lead with all the debugging data without the need to log in to the Next Matter app to investigate.The email is enriched with the X-Custom-Data header that you can decode:
    1. Open the email to view its source. For example:
    • In Gmail, click the three dots (⋮) in the top right and select Show original.
    • In Outlook Web, click the three dots (⋮) and select View source.
    1. Search for X-Custom-Data. X Custom Data image
    2. Copy the data into a base64 decoder. You can use this decoder (external link).
    The decoded data might look like the following:
    Copy
    Ask AI
    {
"instance_id": 5977564,//Unique identifier for the workflow run
"step_id": 328167, //Specific step that failed 
"process_id": 16742, //Workflow ID
"company_id": 330,
"url": "https://app.nextmatter.com/app/live/5977564/step/328167",
"status": null,
"error": "Missing configuration. Configure the step and try again.", //Human-readable message
"body": null,
"debug_errors": {} //Detailed technical error information
}
    The status and body information is displayed for custom integration steps, and debug_errors for most of our no-code steps.

    Workflow stops and shows the 401 error

    Check custom integration steps and verify that the phrase Api-Key is present in the Header.
    1. In the left-hand navigation, click Workflows.
    2. Click the workflow containing the integration step.
    3. Click Settings to edit the step.
    4. Make sure your API key is preceded by the Api-Key phrase.
    Alternatively, a 401 error might mean that the account connected to an integration step got deactivated or deleted. It might also show if the same account was connected in another environment and then disconnected.

    I'm getting an Unauthorized error when I try to push data to Google Sheets

    This might happen when you don’t select Google Slides in the Authorization field in the integration step’s settings.

    Why does my integration step show as skipped?

    This happens if you have selected to skip a failed step. You can configure this in the step’s settings in the On Failure section. Probably the step failed and it was skipped.
    Image of a failed and skipped integration step
    To quickly see what the issue with the step might be, expand the skipped step and right-click to inspect. Next, delete the overlay <div>.
    A screenshot of the CSS code with the overlay settings highlighted

    The data reference gets pushed to an external system as raw variables, not the actual data

    This might happen when you edit the Body in an external JSON editor and then copy it over to Next Matter. Data references need to be selected directly in Next Matter (by clicking the braces and selecting the value from the dropdown).

    Why is the variable I created breaking my integration?

    It might be because there are brackets or braces to the variable name. Make sure the name doesn’t contain any brackets or braces.

    I'm getting a Step not found error

    If you’re getting this error when clicking Test integration in the Complete step automatically template, it’s because the auto-complete step relies on the instance ID of the running instance. Clicking Test integration in the editor with no running instance will always produce this error, even if all placeholders are correct.

    My instance gets stuck on an integration step

    If this happens, try refreshing the screen.

    How do I retry and update a failed step?

    Your integration test might fail with a Bad gateway or Not authorized error. In such cases, you can take over a step, reconfigure it, and retry.
    You can take over a step if you’re a workflow owner or a workflow tech lead.

    The condition I created for a form field doesn't work

    It might be because you’ve edited the value that’s used in the condition, and you haven’t updated the condition itself.

    I'm getting the 429 error

    This means you’ve hit the rate limit and need to monitor your API usage to stay under the 10,000 requests/hour limit. Instead of skipping the step automatically, select the Allow manual retry option and retry the failed step.

    I can't take over an instance

    Check that the instance hasn’t been stopped - stopped instances cannot be taken over.

    My integration fails with 500 Internal Server Error

    This indictes issues with the external service that is being called - check the 3rd party endpoint.

    Step doesn't automatically start

    If this happens, check the following:
    • Has the previous step completed or is it still in progress?
      If the previous step is in progress, the next one won’t start.
      A step will not automatically start if all the required fields in the previous step haven’t been filled in.
    • Is the automation step properly configured? Are there any dependencies and conditions on the step?
    • Was the step modified recently?
      If the workflow was updated (e.g., new automation logic added) after the instance was already running, the changes might not apply retroactively.
    • Is the step expected to be triggered is an automation step?
      Manual steps must be assigned to someone or explicitly opened. Automation steps that follow manual steps require manual steps to be completed.

    ​
    Do the following to troubleshoot:

    1. Preview the instance in the Builder to see the logic flow.
    2. Check instance logs.
    3. Retry trigger:
      • If it’s a webhook: resend it.
      • If it’s conditional: update the input and recheck.
    4. Manually complete the preceding step.

    Read-only table blocks step completion

    If a read-only field is marked as required and prefill fails (i.e., table is empty), users cannot complete the step. Try unchecking the Required option for read-only fields unless prefill is guaranteed.

    My instance fails without any clear error

    This usually happens when one of the following is true:
    • Rate limit has been exceeded (429 status)
    • There are JSON body formatting issues in integration steps (for example, the //this is a placeholder notes are left in the JSON)
    • The required fields are not populated in API calls

      When the workflow configuration is correct, retry the instance.

    My Apple Script integration fails

    Retry the step a few times before skipping it.

    Was this page helpful?

    Branch your workflowsInbox
    youtubelinkedin
    Powered by Mintlify
    Assistant
    Responses are generated using AI and may contain mistakes.