---
name: inferrex-diagnose-flow
description: Find out why an Inferrex flow or system is failing, stopped or not syncing, using read-only checks in a fixed order, then propose the smallest fix and apply it only with the user's agreement. Use when the user reports a failing, stuck, paused or unhealthy flow, pipeline, sync, system or connection in Inferrex, or asks what needs attention.
---

# Diagnose a failing flow or system in Inferrex

Read first. Do not change anything until you can name the cause. Most sudden failures are one of five things: a sign-in the system now refuses, a paused system, a safety stop holding the sync, a repair question waiting for an answer, or records the destination will not accept.

Words: a flow is a pipeline in tool and route names. A failed write is a quarantine row. A repair is a heal. A safety stop is a circuit breaker.

## When to use

- "The orders flow has stopped." / "Nothing has synced since yesterday."
- "Why is this system showing as unhealthy?"
- "What needs my attention in Inferrex?"

## Prerequisites

- **InferrexMCP** at `https://mcp.inferrex.com/mcp` (sign-in or API key in a header), or **InferrexAPI** at `https://api.inferrex.com` with `X-API-Key: $INFERREX_API_KEY`.
- Read-only diagnosis needs read scopes: `workspace:read`, `pipelines:read`, `connections:read`, `jobs:read`, `heals:read`, `monitoring:read`, `pipeline-events:read`, `circuit-breakers:read`. `connections_test_saved_connection` needs `connections:write`, though it changes nothing.
- Fixes need the matching write scope. If a call answers `403 scope_denied`, report the scope named in the message and stop.

## Steps: find the cause

Work down the list. Stop at the first step that explains the failure, then go to "Propose a fix".

1. **Overview.** Call `workspace_get_environment_overview` with `detail: "brief"`. Note every `critical` and `warning` item that names the flow or its systems. For more on one area, call it again with `module` set to that area's key.
2. **Identify the flow.** Call `pipeline_list`, match the user's name, then `pipeline_status` with its `id`. Note `status` (`draft`, `reviewing`, `active`, `paused`, `error`, `upgrading`, `archived`), `source_connection_id` and `target_connection_id`.
   - `draft`: it was never turned on. That is the answer.
   - `paused`: go to step 3.
3. **Check its systems.** Call `connection_list`. For the source and each destination, note `status`, `paused_at`, `reconnect_required_at` and `reconnect_reason`.
   - `paused_at` set: the system is paused, and every flow that uses it is paused with it.
   - `reconnect_required_at` set: someone must sign in again.
4. **Test each sign-in.** Call `connections_test_saved_connection` with each system's `id`. It only reads. A pass is `outcome` `signed-in` or `read-without-sign-in`. Otherwise report `outcome`, `httpStatus` and `detail`. Also call `credentials_list_failing_secrets`.
5. **Read the last runs.** Call `pipeline_history`. Note the latest run's status and its counts of records read, written, skipped and failed. Call `jobs_list` and `jobs_get_job` for the failed run and read `error`.
6. **Look for a safety stop.** Call `monitoring_stream_circuit_breakers_list` with `connection_id`. If one is open, call `monitoring_list_circuit_breaker_records` to see what it holds.
7. **Look for a repair question.** Call `heals_list` with `status: "open"` and `pipeline_id`. For each, `heals_get_heal` gives the `message`, the `question` and its `options`.
8. **Look at failed writes.** Call `pipelines_list_pipeline_quarantine` with `id` and `status: "open"`. Group by `failure_reason`.
9. **Look at events and anomalies.** Call `monitoring_pipeline_events_list` with `pipeline_id`, and `pipelines_get_anomalies`.
10. **Check the mapping version.** Call `pipelines_list_pipeline_mappings`, then `mappings_list_mapping_pipelines` with the mapping id. `upToDate: false` means the flow runs an older version than the one last edited.

## Propose a fix

State the cause in one sentence with the evidence (the tool and the field). Then propose one fix and wait for a yes.

| Cause | Fix | Tool |
|---|---|---|
| Sign-in refused | Replace the credentials. Use `inferrex-replace-credentials`. | |
| Provider sign-in lapsed | A person signs in again in the app, on the system's Sign-in tab. | |
| System paused | Resume it. Flows its pause stopped go live again. | `connections_resume_connection` |
| Flow paused | Turn it back on. A sync starts at once. | `pipeline_activate` |
| Repair question open | Give the user the question and options. Send their answer. | `heals_answer_heal` |
| Failed writes, reason starts `record_validation:` | The record lacks a value the destination requires. It must be corrected in the source system. Nothing to do in Inferrex. | |
| Other failed writes | Usually nothing. The next sync retries each one. To retry one held record now: | `pipelines_release_quarantined_record` |
| Safety stop holding records | The user decides after seeing the held records. | `monitoring_approve_quarantined`, `monitoring_partial_approve`, `monitoring_reject_quarantined`, `monitoring_hold_open` |
| Flow on an old mapping version | Move it, with the version the user reviewed. | `pipelines_apply_mapping_to_pipeline` |
| The system's API changed address or sign-in method | Read it again. For a system in use the new reading waits beside the live one for approval. | `connections_reinfer_connection` |

After a fix, confirm it: run step 4 again for a sign-in fix, or `pipeline_sync` then `jobs_get_job` and `pipeline_history` for a flow fix. Report the result of that run.

## Checks before any write

- Every tool in the "Fix" table changes something. Get a yes for each one.
- `monitoring_reject_quarantined` deletes the held data. Show the held records first and say that it deletes them.
- `monitoring_force_close` closes a stop without a decision on its records. Do not offer it as a first choice.
- `pipeline_activate` starts a full sync at once. Say so.
- Do not run a `full` sync to "see if it helps".

## Equivalents

| Check | InferrexMCP tool | InferrexAPI |
|---|---|---|
| Overview | `workspace_get_environment_overview` | `GET /v1/workspace/overview` |
| One flow | `pipeline_status` | `GET /v1/pipelines/:id` |
| Flows with something waiting | `pipelines_get_pipeline_attention` | `GET /v1/pipelines/attention` |
| Systems | `connection_list` | `GET /v1/connections` |
| Test saved sign-in | `connections_test_saved_connection` | `POST /v1/connections/:id/test` |
| Failing secrets | `credentials_list_failing_secrets` | `GET /v1/workspace/secrets/failing` |
| Runs | `pipeline_history` | `GET /v1/pipelines/:id/history` |
| Job | `jobs_get_job` | `GET /v1/jobs/:id` |
| Safety stops | `monitoring_stream_circuit_breakers_list` | `GET /v1/circuit-breakers` |
| Held records | `monitoring_list_circuit_breaker_records` | `GET /v1/circuit-breakers/:id/records` |
| Repairs | `heals_list`, `heals_get_heal` | `GET /v1/heals`, `GET /v1/heals/:id` |
| Answer a repair | `heals_answer_heal` | `POST /v1/heals/:id/answer` |
| Failed writes | `pipelines_list_pipeline_quarantine` | `GET /v1/pipelines/:id/quarantine` |
| Events | `monitoring_pipeline_events_list` | `GET /v1/pipeline-events` |
| Health scores | `monitoring_get_connection_health` | `GET /v1/monitoring/health` |
| System history | `connection_audit` | `GET /v1/connections/:id/audit` |

## Report back

- The cause, in one sentence, with the evidence.
- What you checked and found clear, so the user knows what was ruled out.
- The fix proposed, whether it was applied, and the result of the run that confirmed it.
- Anything that needs a person in the app or in the source system.

If no step explains it, say so. List what you checked and give the failed job's `id` and `error`. Do not guess.

## Never

- Never change anything before you can name the cause.
- Never reject or force close a safety stop on your own judgement.
- Never answer a repair question for the user.
- Never archive or recreate a flow or a system to clear an error. Mappings, flows and rules refer to them by id.
- Never read a health score for a system marked `unmeasured` as a problem. It means no activity.
- Never ask for, print or log a credential value. Inferrex never returns one.