FIX Doctorsupport@fixdoctor.tech
FIX Knowledge Base

FIX Troubleshooting Guide for Engineers

When FIX connections fail or produce errors, systematic troubleshooting helps identify the root cause quickly. This guide provides a step-by-step procedure for diagnosing common FIX issues, from connection problems to message-level errors.

Step 1: Verify Session Status

First, confirm whether the FIX session is established and active:

  • Check for Logon messages (MsgType=A) in both directions
  • Verify heartbeat messages (MsgType=0) are being exchanged regularly
  • Confirm no Logout messages (MsgType=5) indicating session termination
  • Check sequence numbers are incrementing correctly
  • Verify no session-level rejects (MsgType=3) at the session layer

Step 2: Check Sequence Numbers

Sequence gaps are one of the most common FIX issues:

Symptoms:

  • Missing MsgSeqNum values (e.g., have 1, 2, 4, 5 but missing 3)
  • Out-of-order messages
  • Session rejects with reason related to sequence numbers

Likely Causes:

  • Network packet loss
  • Application crash or restart without proper sequence number persistence
  • Sequence number reset not synchronized between parties
  • Message sent but not acknowledged

Fix:

  • Request gap fill using ResendRequest (MsgType=2) with BeginSeqNo and EndSeqNo
  • If gap fill fails, reset sequence numbers (tag 141=Y) and restart session
  • Ensure sequence numbers are persisted to disk and recovered on restart

Step 3: Analyze Reject Messages

Reject messages provide detailed error information:

  1. Look for MsgType=3 (Reject) messages in the log
  2. Check RefTagID (371) to identify which tag caused the rejection
  3. Check RefMsgType (372) to see which message type was rejected
  4. Read SessionRejectReason (373) for the numeric reject code
  5. Review the Text (58) field for human-readable error description
  6. Inspect the original rejected message to identify the problem

Step 4: Common Symptoms and Causes

Symptom: Connection Refused

Likely Causes:

  • IP address not whitelisted on counterparty firewall
  • Incorrect hostname or port number
  • Network routing issues
  • Firewall blocking outbound connections

Fix: Verify IP whitelisting, test network connectivity with telnet, check firewall rules.

Symptom: SSL/TLS Handshake Failure

Likely Causes:

  • SSL certificate not installed or expired
  • Certificate not in correct keystore location
  • Cipher suite incompatibility
  • Certificate chain issues (missing intermediate CA)

Fix: Verify certificate installation, check expiration dates, test SSL handshake separately.

Symptom: CompID Mismatch Rejects

Likely Causes:

  • SenderCompID or TargetCompID doesn't match counterparty expectations
  • CompID configured incorrectly in application
  • Using wrong CompID for environment (DEV vs PROD)

Fix: Verify CompID configuration matches counterparty documentation, check environment settings.

Symptom: Duplicate ClOrdID Rejects

Likely Causes:

  • Reusing ClOrdID within the same session
  • ClOrdID generation algorithm producing duplicates
  • Application restart without proper ClOrdID tracking

Fix: Ensure ClOrdID uniqueness per session, use UUID or timestamp-based IDs, track used ClOrdIDs.

Symptom: Missing Mandatory Tags

Likely Causes:

  • Required tags not included in message construction
  • Tag filtering removing required fields
  • Incorrect FIX version (different versions have different mandatory tags)

Fix: Review FIX specification for mandatory tags, verify message construction logic, check FIX version.

Symptom: Invalid Timestamp Format

Likely Causes:

  • Timestamp format doesn't match counterparty requirements
  • Timezone issues (not using UTC)
  • Incorrect date/time format (YYYYMMDD-HH:MM:SS vs YYYYMMDD-HH:MM:SS.sss)

Fix: Verify timestamp format matches specification, ensure UTC timezone, test with sample timestamps.

Symptom: Orders Not Executing

Likely Causes:

  • Orders rejected at business level (invalid price, symbol, account)
  • Orders not reaching exchange (routing issues)
  • Market closed or trading halted
  • Insufficient permissions or account issues

Fix: Check for business rejects, verify order parameters, confirm market status, validate account permissions.

Step 5: Diagnostic Tools

Use these tools and techniques for FIX troubleshooting:

  • FIX Log Parser: Upload your FIX logs to FIX Doctor to automatically detect errors, sequence gaps, and issues
  • Network Tools: Use telnet or nc to test connectivity to FIX port
  • SSL Tools: Use openssl to test SSL certificate and handshake
  • Sequence Number Analysis: Check for gaps, duplicates, and out-of-order messages
  • Message Validation: Verify all tags are valid and values are within ranges

Step 6: Systematic Debugging Process

  1. Reproduce the issue: Identify the exact conditions that cause the problem
  2. Collect logs: Gather FIX session logs from both parties if possible
  3. Parse and analyze: Use FIX Doctor or similar tools to parse logs and identify errors
  4. Isolate the cause: Narrow down to session-level vs business-level, specific tags, or network issues
  5. Fix and test: Apply the fix and verify with test messages
  6. Monitor: Watch for recurrence and set up alerts for similar issues

Related Resources

Additional resources for FIX troubleshooting: