AMQERR Logs

When IBM MQ fails a channel bind, rejects a put with reason 2035, or cannot start a listener, the queue manager records what happened in AMQERR logs. These text files are the first place operations teams look because they translate internal failures into readable messages with AMQ identifiers, reason codes, object names, and channel names. Beginners sometimes search application logs while the real explanation sits in AMQERR01.log under the queue manager error directory. This tutorial explains what AMQERR files are, where they live on distributed and z/OS systems, how rotation works, how to read and grep them safely during incidents, how AMQ messages relate to MQI reason codes, correlation with channel status and FDC files, and operational practices so logs are available when you need them—not after disk fills.

What AMQERR Logs Contain

Each line in AMQERR is a queue manager message. IBM assigns message numbers such as AMQ9208 (channel errors), AMQ8077 (authority), or AMQ9638 (SSL handshake). The text usually names the object (queue, channel, listener), the user ID involved (often MCAUSER), and sometimes the remote host or certificate distinguished name. Unlike a binary trace, AMQERR is meant for administrators: you can tail it during a reproduction and see failures as they occur. The log does not replace DISPLAY CHSTATUS or client trace, but it is faster to access and often points to the exact CHLAUTH rule or missing +put grant.

File Location and Rotation

On distributed MQ, the error directory is part of queue manager data. After creating a queue manager named QM1, you typically find /var/mqm/qmgrs/QM1/errors/AMQERR01.log (Linux) or the equivalent under your MQ_DATA_PATH. The dspmq command shows the path: dspmq -m QM1 -o all displays the ERRPATH or you can run echo $MQERR while logged in as the mqm user with the queue manager environment set. When AMQERR01 grows to the configured maximum size, MQ renames it to AMQERR02 and creates a new AMQERR01. If problems persist across rotation, read both files around the incident timestamp. On z/OS, queue manager messages often appear in CSQOUT and related log streams; filename AMQERR01 is a distributed convention—always follow your site's runbook for the platform you administer.

1
2
3
4
5
dspmq -m QM1 -o all | grep -i err
# Example Linux path:
# /var/mqm/qmgrs/QM1/errors/AMQERR01.log
tail -f /var/mqm/qmgrs/QM1/errors/AMQERR01.log
grep -i 'AMQ9638\|2035\|PARIS.TO.LONDON' /var/mqm/qmgrs/QM1/errors/AMQERR01.log

Reading AMQ Messages During an Incident

1. Note the exact time from the application or monitoring alert (UTC if teams span regions).
2. Open AMQERR01 and search ±30 seconds around that time.
3. Copy the full AMQ message ID (for example AMQ9208) and reason code if present.
4. Identify named objects: CHANNEL, QUEUE, LISTENER, AUTHINFO, CHLAUTH rule.
5. Run complementary commands: DISPLAY CHSTATUS, dspmqaut, DISPLAY CHLAUTH.
6. If the message references an internal fault, check the FDC directory the same timestamp.

Channel authentication blocks often log the CHLAUTH rule name—use DISPLAY CHLAUTH('rule') ALL to see whether ADDRESS, SSLPEER, or QMNAME caused the deny. SSL failures log GSKit-related AMQ messages; pair with GSKit trace on a lab reproduction, not production at trace level 15 without planning. Authority failures may show both AMQ8077-style text and reason 2035; fix OAM grants for the effective MCAUSER, not the developer's personal login unless that is the connecting identity.

Common AMQ Message Categories

• Channel and listener — bind failures, sequence number errors, partner not found, TLS handshake.
• Security — CHLAUTH, CONNAUTH, SSL certificate, password authentication failures.
• Object and authority — unknown queue, put inhibited, not authorized, attribute errors.
• Startup and recovery — log full, media recovery, object inconsistencies after unclean shutdown.
• Trigger and process — trigger monitor cannot start APPLICID, initiation queue errors.

Learning a handful of AMQ patterns speeds triage more than memorizing every message ID. When you see AMQ9208 series text, think channel path. When you see AMQ9638, think TLS cipher or certificate. When you see not authorized with 2035, think OAM before firewall. IBM documents each AMQ code in the Knowledge Center—paste the ID into search during incidents.

Explainer: The Queue Manager's Diary

AMQERR is the queue manager's diary of bad news. Applications tell you they failed; AMQERR often tells you why the queue manager said no—wrong user, closed channel, full disk, or broken certificate. You read the diary entry at the same minute the application complained to see the real story.

Correlation With Reason Codes

MQI reason codes returned to programs (2035, 2059, 2085, 2009) appear in AMQERR when the queue manager logs the failure. The completion code is usually 2 (failed) alongside the reason. A single user action may produce one client return code and several AMQ lines if the failure cascades—for example CONNAUTH failure followed by no channel start. Always treat the earliest AMQ line in the second window as the root cause unless a later line clearly supersedes it. Our dedicated tutorials on 2035, 2059, 2085, 2009, 2538, and 2278 errors expand each code; use AMQERR as the evidence source when validating which code fired on the server.

Operational Best Practices

• Ship AMQERR to centralized logging (Splunk, ELK) with retention matching compliance needs.
• Alert on rate spikes of AMQ9208 or AMQ8077, not only on queue depth.
• Protect file permissions—AMQERR may contain hostnames, user IDs, and certificate DNs.
• Monitor disk on the error directory filesystem; a full disk stops new diagnostics.
• During change windows, tail AMQERR live while testing one channel or one application path.

Do not delete AMQERR files while the queue manager is running unless IBM documentation for your release instructs a specific cleanup procedure. Prefer log rotation and archival. For long-running queue managers, ensure AMQERR02 is also collected by your log agent after rotation.

AMQERR vs Application Logs

A Java client might log "MQException 2035" without naming the queue manager user ID. AMQERR on the server names MCAUSER and the queue. A COBOL program on z/OS might show a generic failure; CSQOUT or AMQ-equivalent messages name the profile or resource. Teach developers to send queue manager name, object name, and timestamp with every ticket so operations can grep AMQERR immediately. Client trace (see our strmqtrc tutorial) is the next step when AMQERR shows the server accepted the connection but the client disagrees about timing or protocol.

Explain Like I'm Five: AMQERR Logs

AMQERR is a notebook where the mail-sorting machine writes down every time it could not deliver a letter—wrong address, locked door, or broken key. When your friend says the letter did not arrive, you read the machine's notebook to see the real reason.

Practice Exercises

Exercise 1

On a lab queue manager, reproduce a 2035 by putting to a queue without authority. Capture the AMQ line and the AMQ message ID.

Exercise 2

Write a grep command that finds all SSL-related AMQ messages in the last 1000 lines of AMQERR01.

Exercise 3

Document your site's path to AMQERR for Linux and z/OS in a one-page runbook section.

Frequently Asked Questions

Test Your Knowledge