IBM i Troubleshooting Guide

This page is a triage map, not a message catalogue. Start from what you’re actually seeing — a job that won’t move, an error code, a wait, an abend, or a job that’s just slow — and follow the short procedure under that symptom to narrow down the cause. Each section ends with a link to the deep-dive article for the fix once you know which one applies; this page’s job is to get you there fast, not to repeat that content.

How to Use This Page

1. Identify which symptom category below matches what you’re looking at.
2. Run the short diagnostic procedure for that category. It takes two to five commands and tells you which specific problem you have.
3. Follow the link at the end of the section for the detailed explanation and fix.
4. If a symptom spans two categories (for example, a job in MSGW because of a lock wait), work the MSGW section first — it is read-only and safe, and it will usually reveal the underlying cause.

Symptom: Job Stuck / Not Moving (MSGW)

What you’re seeing: A job sits in WRKACTJOB with status MSGW and does nothing. An interactive session looks frozen, or a batch job hasn’t progressed in its job log for longer than expected.

Diagnostic procedure:

1. WRKACTJOB — confirm the status is MSGW, and note the job name, user, and number.
2. WRKJOB JOB(number/user/name) — open the job.
3. Display the job log, option *JOBLOG, or DSPJOBLOG JOB(number/user/name) — the inquiry message waiting for a reply is usually the last or second-to-last entry.
4. Read the message text and its help (F1) before doing anything else. Do not reply blind.

Why this matters: MSGW almost always means an inquiry message is waiting for an operator reply — frequently an unmonitored escape message that bubbled up with no MONMSG to catch it (see Reading Database Files in CL with DCLF and RCVF for one common source, an unmonitored CPF0864 after RCVF). The job is not actually hung; it is correctly waiting, and the risk is replying incorrectly rather than the wait itself.

Full procedure: IBM i Job Stuck in MSGW Troubleshooting — the safe-first-response runbook, including when it is and isn’t safe to cancel the reply.

Symptom: SQL Error Code in a Job Log or Program

What you’re seeing: An RPG, SQLRPGLE, or client program fails with an SQLCODE/SQLSTATE and a message ID like SQL0204, SQL0501, SQL0802, or SQL0913 in the job log.

Diagnostic procedure — narrow by the message ID first, not the symptom:

If the message ID isn’t one of these four, find its full text and reason code first:

1. DSPJOBLOG to see the message in context, or DSPMSGD MSGID(message-id) MSGF(QSQLMSG) for the catalog text and reason codes.
2. Cross-reference the SQLSTATE and SQLCODE pair against the job log entry before assuming which of the above applies — some message IDs cover several distinct reason codes with different causes.

Full procedure: see the specific SQL error page in the table above; for job log mechanics generally, see IBM i Job Log and CPF Messages Reference.

Symptom: Lock Wait (Job Slow or Timing Out on a Specific File/Row)

What you’re seeing: A job is slow or fails intermittently, specifically around file or record access, but isn’t in MSGW and isn’t showing an obvious SQL error — or it is showing SQL0913 and you need to find who’s holding the lock before deciding how to respond.

Diagnostic procedure:

1. WRKOBJLCK OBJ(library/object) OBJTYPE(*FILE) — lists every job holding a lock on the object and the lock type.
2. For record-level contention specifically, DSPRCDLCK FILE(library/file) MBR(member) — shows which job holds which record lock.
3. Note the job holding the conflicting lock, then WRKJOB on that job to see what it’s doing and how long it’s been doing it. A job that’s been in that state for a long time with no progress is itself worth investigating (it may belong in the MSGW or performance sections above/below).
4. Decide whether to wait, end the blocking job, or change your own job’s wait-time attribute — don’t default to ending the other job without knowing what it’s doing.

Why this matters: WRKOBJLCK and DSPRCDLCK are read-only investigation tools. Running them first, before touching either job, is what keeps this a diagnosis instead of an outage.

Full procedure: SQL0913: Row/Object Lock Timeout covers the SQL-visible form of this in detail, including a conservative retry/handling pattern.

Symptom: Abend / Program Ended Abnormally

What you’re seeing: A job or program ends with an abend message, a function check, or a message like CPF9999 in the job log, and the job stops rather than completing or waiting.

Diagnostic procedure:

1. DSPJOBLOG (or the job’s spooled QPJOBLOG if it already ended) — find the last escape message before the abend; it is usually several messages before the final CPF9999-style summary, which just reports that something failed, not what.
2. Read upward from that last escape message — CL and RPG both send a chain of messages as the error propagates up the call stack, and the root cause is near the bottom of that chain, not the top.
3. Check whether the failing command or statement had a MONMSG (CL) or an error indicator/%ERROR check (RPG) that should have caught it but didn’t match the actual message ID — a mismatched or too-narrow monitor is one of the most common reasons a program abends instead of handling the error.
4. If the program was compiled with a debug view, STRDBG and reproduce the call to see the exact statement, rather than guessing from the job log alone.

Full procedure: IBM i Job Log and CPF Messages Reference for reading the message chain, and IBM i Message Files, Exception Handling and CL for fixing the MONMSG coverage that let the error propagate.

Symptom: Performance (Job or System Slow, No Error)

What you’re seeing: Nothing is failing outright, but a job, subsystem, or the whole system is slower than normal, and there’s no MSGW, no SQL error, and no abend to chase.

Diagnostic procedure:

1. WRKACTJOB — sort by CPU% and check for one or a few jobs consuming disproportionate CPU, and check overall CPU utilization at the top of the screen.
2. WRKSYSSTS — check the memory pool(s) the slow job runs in for a high non-database or database faulting rate; a pool that’s paging heavily will slow every job in it, not just one.
3. If a specific query is slow, check whether it’s using an index at all versus a full table scan — a newly slow query after data growth is frequently a missing or no-longer-selective index, not a system-wide problem.
4. If the slowdown is new and system-wide rather than isolated to one job, check whether a batch window, backup, or save-while-active operation is currently running and competing for the same resources.

Full procedure: IBM i Performance Tuning: Memory Pools, WRKACTJOB, and Collection Services for the pool and job-level diagnosis, and DB2 for i Query Optimization: Visual Explain, SQE vs CQE, Index Design, and the SQL Plan Cache if the slow component is a specific query.

A Note on Scope

This page intentionally does not re-explain the commands or message text covered by the linked articles — each of those is the canonical page for its topic, and duplicating them here would just create two pages that need to stay in sync. If you arrived here from a search for a specific message ID and the table above doesn’t have it, the two general-purpose references to check next are IBM i Job Log and CPF Messages Reference for reading the message itself, and IBM i Message Files, Exception Handling and CL for how to monitor it going forward.

Summary

• Job stuck (MSGW): WRKACTJOB → WRKJOB → read the inquiry message before replying. See MSGW Troubleshooting.
• SQL error code: identify the exact message ID first, then go straight to its dedicated page — SQL0204, SQL0501, SQL0802, or SQL0913.
• Lock wait: WRKOBJLCK / DSPRCDLCK to find the holder before acting. See SQL0913.
• Abend: read the job log from the last escape message upward, not just the final summary message. See Job Log and CPF Messages Reference.
• Performance: WRKACTJOB and WRKSYSSTS to localize the bottleneck before assuming it’s a specific query or job. See Performance Tuning.