Troubleshoot a Workflow Run

Troubleshoot a Workflow Run

A workflow can fail for many reasons.

The problem may come from the input, an AI provider, a local model, a block instruction, a connection, a tool, a branch, or the final output.

The most useful troubleshooting method is to find the first step that did not produce the expected result.

Do not begin by changing every block.

Review the run in order, correct one issue, and test again with a small, non-sensitive example.

Start with the visible symptom

First, identify what you can see.

Common symptoms include:

• the workflow does not start;
• the run remains active for too long;
• a model returns an error;
• no output appears;
• the wrong branch runs;
• a tool fails;
• the output is incomplete;
• the result is incorrect;
• a write action creates a duplicate; or
• the workflow completes but produces an unusable result.

The symptom helps you decide where to look first.

Read the complete status and error

Open the run in RunFlows and read:

• the current status;
• intermediate output;
• warnings;
• error messages;
• tool activity; and
• the final output, when available.

Do not rely only on the last line.

A later error may have been caused by an earlier missing or incorrect result.

Trace the workflow from the beginning

Review each step in order.

Ask:

1. Did the workflow receive the expected input?
2. Did the first block produce a usable result?
3. Did the correct path run?
4. Did the next block receive the information it needed?
5. Did a provider or tool return an error?
6. Where did the first unexpected result appear?

Correct the first failing step before changing later blocks.

Use intermediate output

Intermediate output can reveal where the result changed.

A workflow may use an Emit block to show an early result.

For example:

Input
→ Extract Details
→ Emit Extracted Details
→ Prepare Report
→ Output

If the final report is wrong, first review the extracted details.

When the extracted details are already incorrect, changing the report block will not solve the original problem.

Confirm the workflow input

Check that the input:

• matches the workflow's intended purpose;
• contains the required information;
• is not empty;
• is not larger than the selected model can handle;
• uses a supported format; and
• does not contain unrelated content that confuses the process.

A workflow designed for meeting notes may not work correctly with a full contract or an image.

Test with a short example that clearly fits the task.

If the workflow does not start

Check that:

• the correct flow is selected;
• the flow has been saved;
• the starting block is connected;
• the workflow contains a valid path;
• required block settings are complete;
• the selected provider is available; and
• any required Gene or tool setup has been completed.

Open the workflow in Studio and review visible validation warnings.

A disconnected Input block or incomplete AI block can prevent the run from starting normally.

If the workflow is missing from RunFlows

Confirm that:

• the flow was saved in Studio;
• it has a name;
• you are viewing All or Local;
• RunFlows has been refreshed;
• the flow was not renamed; and
• it was not removed.

For a Gene-provided flow, confirm that:

• the Gene is installed;
• it has been synced;
• the flow is included with that Gene; and
• any required setup is complete.

If the run stays active for too long

A long-running workflow may be waiting on:

• a large local model;
• a cloud provider;
• a large input;
• several AI steps;
• image generation;
• an external tool;
• a slow network connection; or
• a service that is no longer responding.

Review the latest visible output.

Do not start the same workflow repeatedly while the first run may still be active.

For a local model, confirm that its application and model service are still running.

If a cloud model fails

Common cloud-provider problems include:

• an inactive or incorrect API key;
• no internet connection;
• unavailable model access;
• an unavailable provider service;
• a request that is too large;
• a timeout; or
• an account-side restriction.

Test the same provider and model in Workbench with a short message.

If the test also fails in Workbench, correct the provider setup before changing the workflow.

If Workbench succeeds, review the workflow input, model selection, and block instruction.

If a local model fails

Check that:

• Ollama, LM Studio, or the compatible local service is open;
• the local server is running;
• the required model has been downloaded;
• the model is loaded when needed;
• the configured address and port are correct;
• the model appears in Feluda; and
• your computer has enough available memory.

Test the model in Workbench.

Use a smaller model when the current model repeatedly runs out of memory or responds too slowly.

If the model returns no useful response

The problem may be the instruction rather than the connection.

Check whether the block instruction explains:

• one clear task;
• the source information to use;
• the required details;
• the expected format;
• how to handle missing information; and
• what the model should not invent.

Replace vague instructions such as:

Analyse this.

With a more testable instruction:

Read the input and return:

1. a short summary;
2. the main decisions;
3. a table with Owner, Action, and Deadline; and
4. unanswered questions.

Use only the provided input.
If a detail is missing, write "Not provided."

Test the revised instruction in Workbench before saving it in Studio.

If the output is empty

Trace the full path from Input to Output.

Check whether:

• the Input block received content;
• the first processing block returned a value;
• the correct branch ran;
• a tool returned data;
• the final path reaches an Output block;
• the Output block receives the expected result; and
• a warning or error appeared earlier.

Empty output often means an earlier step returned nothing.

If the output is incomplete

Check whether:

• the source itself is incomplete;
• the model ignored part of the instruction;
• the input was too long;
• a field was missing;
• an earlier extraction step lost information;
• the wrong branch was selected; or
• a tool returned only part of the expected data.

Ask the model to make missing information visible.

For example:

If a required field is missing, write "Not provided."
Do not guess.

If the output contains invented details

Add a source boundary to the relevant AI instruction.

For example:

Use only information from the provided source.
Do not create names, dates, amounts, deadlines, or decisions.
Mark missing details as "Not provided."

Test several examples where information is intentionally missing.

If the problem continues, compare another model.

If the wrong branch runs

Review the classification or decision step.

For an LLM Label block, check:

• whether the labels are clearly different;
• whether label descriptions overlap;
• whether an Other or Human Review label exists;
• whether the test input could reasonably fit two labels; and
• whether each label connects to the intended path.

For an Expression block, check:

• the value being tested;
• spelling and capitalisation;
• number and date formats;
• missing values;
• the comparison rule; and
• the fallback route.

Test one example for every branch.

If extracted fields are wrong

Review each extraction field against the source.

Check whether:

• the field name is clear;
• the source contains more than one possible value;
• dates or amounts use an unexpected format;
• the model guessed a missing value;
• long input caused information to be missed; and
• the next block received the correct structured result.

Use specific field names.

Prefer:

• Invoice Date;
• Total Amount;
• Customer Name; and
• Required Action.

Avoid unclear labels such as:

• Date;
• Value; or
• Info.

If a connection is wrong

Open the flow in Studio and inspect the canvas.

Look for:

• an unconnected block;
• a connection pointing in the wrong direction;
• a branch that ends without an Output block;
• an old connection that skips a new block;
• a result sent to the wrong next step; or
• an error path connected to the normal success output.

Trace every path visually from Input to an intentional endpoint.

If a tool is missing

A tool may be unavailable because:

• its Gene is not installed;
• the Gene has not been synced;
• an MCP connection is inactive;
• a required setting is incomplete;
• the selected model does not support the required tool use;
• the tool is not enabled for that block; or
• Feluda needs to be refreshed.

Review the Gene or connection setup.

Confirm that the tool appears in Workbench before relying on it in a workflow.

If a tool returns an error

Review:

• the tool name;
• the information passed to it;
• required settings;
• account or access details;
• the destination;
• permission restrictions;
• the connected service; and
• the returned error message.

A tool can fail because the request is unsupported even when the connection itself works.

Test the smallest supported action first.

If a tool returns the wrong result

Check whether:

• the correct tool was selected;
• the search or action input was accurate;
• the expected source was used;
• the returned data is current;
• filters were applied correctly; and
• the next AI step interpreted the tool result accurately.

When accuracy matters, separate the raw tool result from the model's summary.

If a write action times out

Do not retry immediately.

First:

1. check the destination;
2. review the tool output;
3. confirm whether the action completed;
4. look for a created file, Journal entry, message, or update; and
5. retry only when you know the earlier action did not finish.

This helps prevent duplicates.

If a write action affects the wrong destination

Stop running the workflow.

Review:

• the selected tool;
• destination fields;
• identifiers;
• file paths;
• account selection;
• names or titles; and
• values passed from earlier blocks.

Correct the destination and test with a safe example.

Important write actions should remain easy to review before execution.

If the workflow stops after an error

Confirm whether the failed step has an error connection.

A visible error path can return a useful message such as:

The selected model is unavailable.
Review the provider and run the workflow again.

Without an error path, the workflow may stop without a clear final result.

Add and test error routes for predictable failures.

If the workflow reports success but the result is wrong

A completed state only means the flow reached an endpoint.

Review:

• the input;
• the selected path;
• intermediate output;
• extraction fields;
• model instructions;
• tool results;
• final formatting; and
• source accuracy.

The run may be technically successful while the content is unsuitable.

If similar inputs produce very different results

Variation may be caused by:

• a broad instruction;
• overlapping labels;
• an unsuitable model;
• missing format rules;
• inconsistent source structure;
• tool results that change; or
• too many tasks inside one AI block.

Improve consistency by:

• defining the output structure;
• separating large tasks into smaller blocks;
• using clearer categories;
• adding missing-value rules;
• testing the same examples across models; and
• reducing irrelevant input.

Compare the workflow with Workbench

Workbench is useful for isolating an AI step.

Copy the block instruction and test it with the same source.

If it fails in Workbench, improve the instruction or choose another model.

If it works in Workbench but fails in the flow, review:

• the information passed from the previous block;
• the workflow model selection;
• tool availability;
• the branch path; and
• the output connection.

Change one thing at a time

Avoid changing the instruction, model, labels, tools, and connections at the same time.

Change one item.

Run the same test again.

Record whether the result improved.

This makes the cause easier to identify.

Use a small repeatable test

Keep one short example for troubleshooting.

For a summary workflow:

The team approved the revised homepage.
Sam will prepare the final files by Friday.
The launch date has not been decided.

The expected result should include:

• the approved homepage;
• Sam's action;
• the Friday deadline; and
• the missing launch date.

Reuse this example after each correction.

Re-test every affected path

After changing a workflow, test:

• the normal path;
• every changed branch;
• the fallback path;
• the error path;
• missing information;
• unexpected input; and
• any tool action.

A correction for one path can create a new problem elsewhere.

Review local and cloud privacy

Troubleshooting often involves re-running information.

Before doing so, confirm:

• which provider receives the input;
• whether the model is local or cloud-based;
• which tools are active;
• whether an external service receives data;
• whether test information can replace real information; and
• whether logs or destinations contain sensitive output.

Use non-sensitive sample data whenever possible.

Know when to stop retrying

Stop repeated runs when:

• the cause is unknown;
• a write action may already have completed;
• the same error appears repeatedly;
• a connected service is unavailable;
• sensitive data may be sent incorrectly;
• the workflow affects the wrong destination; or
• the result cannot be reviewed.

Investigate the cause before continuing.

Repeated execution can create more confusion or duplicate actions.

A practical troubleshooting routine

Use this routine:

1. Read the run status and full error.
2. Confirm the input.
3. Review intermediate output in order.
4. Find the first unexpected result.
5. Test the provider or model in Workbench.
6. Review the relevant block in Studio.
7. Check branches, tools, and connections.
8. Change one item.
9. Save the workflow.
10. Re-run a small sample.
11. Test every affected path.
12. Confirm write actions before retrying.

This keeps troubleshooting focused and reduces unnecessary changes.