Troubleshooting
This guide is organised by what you see on screen. Each entry explains what you see, why it happens and what to do.
Where to look first
Almost every problem becomes clear in one of these three places:
- The component itself. A yellow border means a required field is missing. A red triangle means it failed in the last run: hover over it to read the reason.
- Executions, on the left of the Playground. It lists the steps of the last test and what each component received and returned.
- Executions Logs, in the side menu. It keeps every run, including those coming from other applications and from the Scheduler. Click View on a run and select the step of the component that failed: in Output, the
errorMessagetext explains the error. See Executions log.
The flow doesn’t run
”Oops! Looks like you missed something” appears
What you see. When you test the flow, the Oops! Looks like you missed something warning appears with a list of components and fields, for example Gemini is missing Credential. The affected components have a yellow border.
Why it happens. Those components are missing a required field. NappAI doesn’t run the flow until they are complete.
What to do. Open each component in the list and fill in the field shown. If it’s Credential, choose a credential or create one with Add new credential. Some fields only appear with certain operations: if you change a component’s Operation, check its fields again.
”Error building flow” appears
What you see. The Error building flow warning with a message below it.
Why it happens. The flow couldn’t be started. The message below says why.
What to do. Read the message. If it mentions an execution profile or too many runs, see An execution profile refuses the run. Otherwise, check that the flow’s connections are correct and test again.
A component never runs
What you see. The flow finishes, but a component shows neither a green tick nor a red triangle, and it doesn’t appear in Executions.
Why it happens. The flow never reached it. Usually an earlier component sent the flow elsewhere, for example a Conditional Router whose condition wasn’t met, or an earlier component returned nothing.
What to do. In Executions, check the output of the last component that did run. Make sure it returns what the next one expects; in a Conditional Router, that the text matches Match Text.
A component shows an error
What you see. The component has a red triangle and the run appears as failed.
Why it happens. The component received something it didn’t expect, the external service rejected the request, or the service didn’t respond. The exact reason is in the error message.
What to do.
- Hover over the red triangle, or open the run and select the component’s step, to read the error.
- Check in Input what it received. Many errors happen because the previous component returned something empty or in a different shape.
- If the error comes from the external service, check the credential (next section) and the data you send: an identifier that doesn’t exist, a model that isn’t available, or a field in a format the service doesn’t accept.
- Fix it and run again. With the component’s play button you run the flow only up to that point.
A credential fails
The service rejects the access
What you see. The component that uses the credential fails and its error says the service doesn’t accept the key or the access.
Why it happens. The key has been revoked or has expired in the service, it was mistyped, or the account doesn’t have permission for what the component asks. With services you sign in to, such as Google, access also expires if you change your password or remove the permission from your account.
What to do.
- For a key: edit the credential in Credentials, type the key again and click Update. Secret values aren’t shown, so you have to type them again.
- For a service you sign in to: edit the credential and click Revalidate to sign in again.
- If the component needs to write and the credential was created with read-only access, create another credential with the right access.
See Credentials.
It works in testing and fails in production, or the other way round
Why it happens. The credential can have different values per environment, and the deployed version runs with the environment saved when it was created.
What to do. Edit the credential and check the Environments section. Check in Version History which environment the deployed version was created with. See Environments.
A component has lost its credential
What you see. A component that used to work now has a yellow border.
Why it happens. The credential it used was deleted, or the flow was imported from another account.
What to do. Choose another credential in its Credential field.
The credential can’t be saved
If you see Error: Name must be unique when creating it, you already have another credential for the same service with that name. Choose a different one.
The playground doesn’t answer as expected
There is no field to type in
Why it happens. The flow has no Chat Input. In that case the playground shows a form with the flow’s inputs and the Run Flow button.
What to do. Fill in the form and click Run Flow, or add a Chat Input if you want to test it as a chat.
It stays on “Building…” for a long time
Why it happens. A component is taking time: a language model with a lot of text, an agent using several tools in a row, or a slow external service.
What to do. Check in Executions which step is running. If the flow has an execution profile with a maximum time, the run stops when it goes over it.
The test button is disabled
Why it happens. Your role doesn’t allow testing flows, or the flow was shared with you at the Can view level. Hovering over it shows Your role doesn’t allow this (test flows).
What to do. See You’re missing a permission.
”Stream connection failed” appears
What you see. An Error warning with the text Stream connection failed.
Why it happens. The connection between your browser and the run was cut, for example by a network drop.
What to do. Check your connection, reload the page and test again. If the run finished, its result is in Executions Logs.
The flow starts with Telegram, WhatsApp or another application
Why it happens. Messages from those applications reach the flow’s published version, not the playground.
What to do. Deploy a version and connect the application from its tab in API Access. See Versions and publishing.
For a voice agent’s playground, see Voice agent troubleshooting.
The agent doesn’t answer as expected
It doesn’t use the right tool
Why it happens. The agent chooses a tool by its description. If it’s vague or similar to another tool’s, it can get it wrong.
What to do. In each tool’s Advanced tab, write in Tool Description what it does, what it needs and what it can’t do. For example: Reads the products in the Products table. It can’t create or delete records.
The tool receives fixed or empty values
Why it happens. Only fields marked as Defined by AI are filled in by the agent. The rest always use the value typed in the component.
What to do. In the tool’s component, click the sparkles button on each field the agent should decide.
It makes up data or doesn’t follow the format
What to do. Make the System Prompt more specific: say what it must do, where it should get the information from (for example, answer only with what your tools return) and what to do if it doesn’t find it. If you need an answer with a fixed shape, describe that shape with an example.
It does too many things at once
What to do. If an agent has many tools or very long instructions, split the work: one agent that classifies the request and several specialised agents, each with few tools. The customer service use case shows how.
A published flow returns an error
The flow has no deployed version
What you see. In API Access, in Production mode, the Deploy a version button appears. In the Scheduler, the schedule can’t be saved.
What to do. Deploy a version. See Versions and publishing.
The call answers with code 401
Why it happens. The call doesn’t carry the API key, or the key isn’t valid, for example because its secret was regenerated or it was deleted.
What to do. Copy the code again from API Access with the right key, or update the secret in the calling application. See API keys.
Changes don’t show in production
Why it happens. You changed the draft. Production calls use the deployed version.
What to do. Create a new version with the changes and deploy it.
The call works but the result is wrong
What to do. Find the run in Executions Logs, filtering by flow and date, and check step by step what each component did.
An execution profile refuses the run
”Run blocked by the execution profile”
What you see. The Run blocked by the execution profile warning, with the profile’s name and the component or model that isn’t allowed. From another application, the call fails for the same reason.
Why it happens. The flow contains a component its profile blocks, or uses a model the profile doesn’t allow. It also happens when testing in the playground.
What to do. Remove that component from the flow or change the model to an allowed one. If the flow needs what the profile blocks, ask whoever manages the profiles to change the profile or assign another one.
”Too many runs (429)”
What you see. The Too many runs (429) warning: This flow ran too many times in the last minute. Wait a moment and try again. From another application, the call answers with code 429.
Why it happens. The flow has reached its profile’s Runs per minute limit.
What to do. Wait for the minute to pass. If the limit is too low, ask for it to be raised.
The run stops before finishing
Why it happens. It went over its profile’s Max run time (seconds). The run ends with an error.
What to do. Check in Executions Logs which step takes longest and simplify it, or ask for the maximum time to be extended.
See Execution profiles.
You’re missing a permission
A button appears disabled
What you see. When you hover over it: Your role doesn’t allow this (…), with the missing permission, for example manage credentials.
Why it happens. Your role in the team doesn’t include that action.
What to do. Ask the account owner to change your role. See Roles and permissions.
You can’t open a page
What you see. You can’t open this page and Your role doesn’t allow you to (…). Ask the account owner if you need it.
What to do. As above: the owner can change your role.
”You don’t have permission to do this” appears
What you see. A You don’t have permission to do this warning after trying an action.
Why it happens. The action needs a permission your role doesn’t have, or the flow was shared with you at a level that doesn’t include it.
What to do. If the flow belongs to someone else, ask them to share it with you at a higher level. See Share a flow. If it’s in your account, ask the owner to change your role.
”Error uploading file” appears when importing a project
Why it happens. The file isn’t a project exported from NappAI, or it’s damaged.
What to do. Export the project again from its original account with Export and import it again. See Projects.
If you still can’t solve it
Write to the NappAI team from Contact us, in your user menu. Include the flow’s name, the date and time of the run, and the error message copied from Output.