Troubleshooting

This page covers the five failure categories most commonly seen in Flexor deployments at alternative asset managers, with diagnosis steps and fixes.

Failure category 1 - Agent not triggering

Symptom: A scheduled agent has not run within its expected window.

Diagnosis steps:

# Check agent status
flexor agents get feed-monitor --env production

# Check recent trigger history
flexor audit --agent feed-monitor --limit 10

Common causes and fixes:

Cause	Fix
Agent is paused	flexor agents unpause --agent feed-monitor --env production
Cron expression is invalid	Validate with flexor validate --agent feed-monitor; fix the cron in the YAML and redeploy
Vault is out of sync	flexor sync --vault company && flexor deploy --agent feed-monitor --env production
Environment mismatch	Confirm environment: production in the agent YAML matches your target

Failure category 2 - Skill fails with input validation error

Symptom: Agent run fails at a specific task step. Audit log shows SKILL_INPUT_VALIDATION_ERROR.

Diagnosis:

flexor logs --run <run_id> --verbose

Look for the inputs_received section in the failed step. Compare it to the skill’s input schema.

Common causes:

• A captured variable from a previous step is null because that step failed silently
• A template expression resolved to an unexpected type (string where integer expected)
• A required input was not passed

Fix: Trace back to the step that should have populated the variable. Add an explicit null check:

- condition: "{{ captured_var != null }}"
- skill: downstream-skill
  args:
    input: "{{ captured_var }}"
- end_condition

Failure category 3 - PlexiFact connection error

Symptom: Agent fails at any PlexiFact skill invocation. Error: PLEXIFACT_CONNECTION_TIMEOUT or PLEXIFACT_AUTH_FAILED.

Diagnosis:

flexor status --env production

Check the PlexiFact connection: line. If it shows degraded or unavailable:

flexor connections test --source plexifact --env production

Common causes and fixes:

Error	Cause	Fix
PLEXIFACT_CONNECTION_TIMEOUT	Network issue or PlexiFact is down	Check PlexiFact status; retry in 10 minutes
PLEXIFACT_AUTH_FAILED	API key expired or rotated	Update the key reference in vault.json under data.catalog; sync and redeploy
PLEXIFACT_CATALOG_NOT_FOUND	Wrong catalog URI in vault.json	Verify the URI with your PLEXI technical contact; staging and production URIs differ

Failure category 4 - Agent runs but produces no output

Symptom: Agent completes with status: success but the expected notification was not sent and/or the expected record was not created.

Diagnosis:

flexor logs --run <run_id> --verbose

Look at the decisions section. If a condition step evaluated to false, the downstream tasks were skipped.

Common causes:

• The condition logic is inverted (e.g., {{ result.is_fresh }} when you meant {{ !result.is_fresh }})
• The upstream skill returned a value outside the expected range (e.g., staleness_minutes is 0 because the feed metadata fetch returned an error that was swallowed by on_error: skip)

Fix: Run the agent manually with debug output:

flexor run feed-monitor --now --env sandbox --debug

The --debug flag prints each step’s inputs, outputs, and condition evaluation results.

Failure category 5 - Vault sync conflict

Symptom: flexor sync fails with VAULT_CONFLICT_ERROR.

Diagnosis:

flexor sync --vault company --dry-run

Look for CONFLICT: lines in the output.

Common causes:

• Two operators edited the same vault file and both tried to sync
• A local file was modified while a deployment was in progress

Fix:

# View the conflict details
flexor sync --vault company --show-conflicts

# Accept the remote version (discard local changes)
flexor sync --vault company --strategy accept-remote

# Accept the local version (overwrite remote)
flexor sync --vault company --strategy accept-local

# Open a diff for manual resolution
flexor sync --vault company --strategy manual

For L2 (company) vaults, always resolve conflicts manually. Never accept a remote overwrite without reviewing what the remote version contains.

Escalation to PLEXI support

If none of the above applies, escalate to PLEXI support:

flexor support bundle --run <run_id>

This generates a support bundle (sanitized of credentials and PII) that you can share with your PLEXI technical contact. Include the bundle ID and a brief description of the expected vs. actual behavior.

Support response time: same business day for production failures on Full Stack CTO and Advisory + Platform tiers. Next business day for all other tiers.