Error messages lie to agents. Verification tells the truth.

Our coding agent was stuck in a 47-minute debugging session yesterday. The error was clear: "Connection refused on port 3000." The agent tried restarting the server, checking firewall rules, examining network configs, even rebuilding the Docker container.

The server was running fine on port 3001.

This is the verification gap that kills agent productivity. Agents read error messages like gospel, but error messages lie constantly. They're written by humans who assumed different contexts, different setups, different states.

The fix isn't better error parsing. It's outcome verification.

Instead of trusting "Connection refused on port 3000"

Your agent should verify:

• What ports are actually listening: netstat -tlnp
• What the config file actually says: grep -r "port" .
• What processes are actually running: ps aux | grep node

We built this verification pattern into our coding agent's error handling:

def handle_connection_error(error_msg, expected_port):
    # Don't trust the error message
    actual_ports = get_listening_ports()
    running_processes = get_process_list()
    config_ports = scan_config_files()
    
    return {
        'error_claim': error_msg,
        'actual_state': {
            'listening_ports': actual_ports,
            'processes': running_processes,
            'configured_ports': config_ports
        }
    }

The pattern works for any error category:

"File not found" → List directory contents, check permissions, verify the path exists

"Authentication failed" → Check what credentials are actually being used, verify the auth endpoint, test with curl

"Build failed" → Check what actually got compiled, verify dependencies are installed, examine the actual build artifacts

Warning: This adds 2-3 verification commands per error. Your token costs will increase 20-30%. But debugging time drops 70%. The math works out.

The verification habit prevents the expensive debugging loops where agents chase phantom problems for hours. Yesterday's 47-minute debugging session would have been a 3-minute port discovery.

Error messages are suggestions. Verification is truth. Teach your agent the difference.