Skip to content

QWK.NET ‐ Troubleshooting

Jump to bottom
Agent 57951 edited this page Jan 19, 2026 · 2 revisions

Troubleshooting

This guide helps diagnose and resolve common issues when working with QWK.NET. For detailed explanations of format behaviour, see the linked canonical documentation.

Parsing Failures

Exception: QwkFormatException in Strict Mode

Symptom: QwkFormatException thrown when opening packet in Strict mode.

Likely Cause: Packet contains structural errors or missing required fields that violate the QWK specification.

What to Check:

  • Exception message and Location property for specific error details
  • Whether packet is genuinely malformed or just uses format variations
  • If packet works in Lenient mode (indicates format variation, not corruption)

Where to Read Next:

Packet Fails to Open

Symptom: QwkPacket.Open() throws exception or returns null.

Likely Cause: Archive format not supported, file corruption, or missing required files (CONTROL.DAT, MESSAGES.DAT).

What to Check:

  • Archive format (ZIP is built-in, other formats require extensions)
  • File exists and is readable
  • Archive contains CONTROL.DAT and MESSAGES.DAT files
  • Try Salvage mode for corrupted archives

Where to Read Next:

Messages Not Parsing

Symptom: Packet opens but packet.Messages is empty or missing expected messages.

Likely Cause: Malformed message headers, incorrect block counts, or truncated MESSAGES.DAT file.

What to Check:

  • Validation report for warnings about message parsing
  • Whether messages appear in Lenient/Salvage modes but not Strict
  • MESSAGES.DAT file size matches expected content

Where to Read Next:

Validation Warnings and Errors

Many Validation Warnings

Symptom: ValidationReport contains numerous warnings but packet appears to work.

Likely Cause: Packet uses format variations common in real-world BBS packets (date formats, missing fields, etc.).

What to Check:

  • Warning messages to identify specific issues
  • Whether warnings are about format variations (normal) or corruption (problematic)
  • If packet data is still usable despite warnings

Where to Read Next:

Validation Errors in Lenient Mode

Symptom: ValidationReport.Errors contains entries even in Lenient mode.

Likely Cause: Structural errors that prevent parsing but don't halt processing (e.g., corrupted index entries, malformed headers).

What to Check:

  • Error messages and locations for specific issues
  • Whether errors prevent data access or are just logged
  • If Salvage mode recovers more data

Where to Read Next:

Unexpected Validation Failures

Symptom: Packet that should be valid fails validation.

Likely Cause: Using Strict mode with packets containing format variations, or validation logic detecting legitimate issues.

What to Check:

  • Validation mode (Strict vs Lenient)
  • Specific validation error messages
  • Whether packet works correctly in Lenient mode

Where to Read Next:

Encoding-Related Display Issues

Box-Drawing Characters Display Incorrectly

Symptom: BBS names or message content show accented letters or symbols instead of box-drawing characters.

Likely Cause: Wrong encoding used when reading or displaying packet content (e.g., Latin-1 instead of CP437).

What to Check:

  • Whether QWK.NET is being used correctly (uses CP437 by default)
  • If custom encoding is being applied incorrectly
  • Console or display system encoding settings

Where to Read Next:

Accented Characters Wrong

Symptom: Names with accents (e.g., José) display as José or Jos?.

Likely Cause: CP437 accented characters decoded with wrong encoding or fallback policy.

What to Check:

  • Encoding used for text display
  • Fallback policy settings
  • Whether issue occurs during reading or display

Where to Read Next:

Line Breaks Not Working

Symptom: Message bodies appear as single lines or breaks in wrong places.

Likely Cause: 0xE3 line terminators not being processed correctly, or wrong LineEndingMode used.

What to Check:

  • LineEndingMode setting if custom processing used
  • Whether message.Body.Lines property works correctly
  • Raw text content for 0xE3 terminators

Where to Read Next:

Index-Related Message Ordering Problems

Messages in Wrong Order

Symptom: Messages appear out of sequence or missing messages in sequence.

Likely Cause: Corrupted or incorrect index file, or index file from different packet version.

What to Check:

  • Validation report for index-related warnings
  • Whether sequential enumeration produces correct order
  • If index file matches current MESSAGES.DAT content

Where to Read Next:

Missing Messages

Symptom: Some messages not accessible via index, but present in MESSAGES.DAT.

Likely Cause: Index entries skipped due to invalid offsets, or index file incomplete.

What to Check:

  • Validation report for skipped index entries
  • Whether messages accessible via sequential enumeration
  • Index file entry count vs actual message count

Where to Read Next:

Index File Errors

Symptom: Warnings about index file size, negative offsets, or offsets beyond file size.

Likely Cause: Corrupted index file, truncated file, or index from different packet.

What to Check:

  • Specific error messages in validation report
  • Index file size (must be multiple of 4 bytes)
  • Whether sequential enumeration works as fallback

Where to Read Next:

Unexpected Packet Contents

Missing Expected Fields

Symptom: packet.Control.BbsName is empty or "UNKNOWN", or other fields missing.

Likely Cause: Empty or missing required fields in CONTROL.DAT, or validation mode applied defaults.

What to Check:

  • Validation report for missing field warnings
  • Whether fields are truly missing or just empty strings
  • Validation mode used (Strict vs Lenient)

Where to Read Next:

Unexpected Conference Numbers

Symptom: Conference numbers have gaps or don't start at 0.

Likely Cause: Non-sequential conference numbering (common in real-world packets).

What to Check:

  • Whether gaps are intentional (conferences deleted/renumbered)
  • If messages reference non-existent conferences
  • Validation report for conference-related warnings

Where to Read Next:

QWKE Features Not Detected

Symptom: Long headers or extension files not accessible despite being present.

Likely Cause: Kludges not parsed correctly, or extension files not detected in archive.

What to Check:

  • Whether TOREADER.EXT or TODOOR.EXT files exist in archive
  • If long headers are in message kludges collection
  • Archive file listing for extension files

Where to Read Next:

Date Fields Show MinValue

Symptom: packet.Control.CreatedAt or message.DateTime is DateTime.MinValue.

Likely Cause: Invalid or unparseable date format in packet.

What to Check:

  • Validation report for date parsing warnings
  • Raw date strings in CONTROL.DAT or message headers
  • Whether date format is supported variant

Where to Read Next:

General Debugging Tips

Check Validation Report

Always examine packet.ValidationReport for detailed issue information:

ValidationReport report = packet.ValidationReport;
if (!report.IsValid)
{
    Console.WriteLine(report.ToHumanReadableString());
    // Or export for analysis:
    File.WriteAllText("report.json", report.ToJson(indented: true));
}

Try Different Validation Modes

If packet fails in one mode, try others:

  • Strict → Lenient: Often resolves format variation issues
  • Lenient → Salvage: May recover data from corrupted packets

Preserve Raw Data

When debugging, access raw properties to see original bytes:

  • message.Body.RawText - Original message body bytes
  • packet.Control.RawLines - Original CONTROL.DAT lines
  • Index entry RawMsbinBytes - Original MSBIN float bytes

Further Reading

Clone this wiki locally