AI_AGENT_OS/docs/kci-processing-jobs/troubleshooting-guide.md

KCI Processing Jobs Troubleshooting Guide

Use this guide when a processing job fails, behaves strangely, or produces unexpected output.

First Questions

1. Which job failed?
2. Which environment failed?
3. When did it last succeed?
4. What input file or batch was involved?
5. Did the job start, partially run, or never start?
6. What changed recently?

Initial Checks

• Confirm the trigger ran.
• Check the job history or scheduled task history.
• Check logs for the failed time window.
• Confirm input files exist.
• Confirm files are not locked.
• Confirm expected output location is reachable.
• Confirm the job account has required permissions.
• Confirm disk space is sufficient.
• Confirm required downstream systems are available.

File Processing Checks

• File name matches expected pattern.
• File extension is expected.
• File size is reasonable.
• File is not empty.
• File is not still being copied.
• File encoding or format is expected.
• PDF can be opened and is not corrupt.
• Required pages, forms, or records are present.

Scheduled Task Checks

• Task is enabled.
• Trigger is correct.
• Last run time matches expectation.
• Last run result is understood.
• Run account is correct.
• Working directory is correct.
• Script path is correct.
• Arguments are correct.
• Highest privileges setting is correct when needed.
• Network paths are accessible from the task account.

Safe Recovery

Before rerunning:

• identify whether output was partially created
• identify whether database records were changed
• identify whether files were moved or archived
• identify whether downstream notifications were sent
• confirm duplicate-processing risk
• confirm who approves the rerun

Escalation Notes

Escalate when:

• customer-facing output is wrong
• production data may be duplicated or missing
• credentials or permissions appear broken
• the job is repeatedly failing
• the recovery path is unclear
• rerunning could create duplicates

Incident Notes Template

Date/time:
Job:
Environment:
Input/batch:
Observed symptom:
Expected result:
Last known successful run:
Recent changes:
Checks performed:
Current state:
Next action:
Owner: