Troubleshooting - edgeof8/tIRC GitHub Wiki

This page provides guidance on troubleshooting common problems you might encounter while using tIRC. For detailed logging and debugging techniques, refer to the Debugging And Logging page.

General Troubleshooting Steps

  1. Check Logs: This is often the first and most important step. Increase log verbosity if necessary (see Debugging And Logging).
  2. Verify Configuration: Ensure your config/tirc_config.ini is correctly set up, especially server details, nicks, and authentication info. Compare with tirc_config.ini.example.
  3. Restart tIRC: Sometimes, a simple restart can resolve temporary glitches.
  4. Update tIRC: Ensure you are running the latest stable version of tIRC, or the specific version you intend to use.
  5. Disable Scripts: If you suspect a script might be causing issues, try temporarily disabling custom scripts (via the [Scripts] section disabled_scripts in config, or by moving them out of the scripts/ directory) to see if the problem persists.
  6. Check Network Connection: Ensure your internet connection is stable and that no firewalls are blocking tIRC's access to IRC ports.

Common Problem Areas

Connection Issues

  • Symptom: Cannot connect to server, "Connection refused", timeout errors.

    • Check: Server address and port in config.ini.
    • Check: SSL/TLS settings (ssl = true/false). Some servers use non-standard ports for SSL (e.g., 6697) vs. non-SSL (e.g., 6667).
    • Check: verify_ssl_cert setting if using SSL. Set to false if the server uses a self-signed certificate (use with caution).
    • Check: Network connectivity and firewalls.
    • Use: /rawlog on to see low-level connection attempts.

  • Symptom: Repeatedly disconnected shortly after connecting.

    • Check: Nickname conflicts (is your chosen nick already in use or registered to someone else?).
    • Check: NickServ identification (nickserv_password or SASL settings). Many servers require identification.
    • Check: Server messages in the Status window or logs for reasons (e.g., "Authentication failed", "Banned").

Configuration Problems

  • Symptom: Settings not taking effect, client behaving unexpectedly.
    • Check: Syntax in tirc_config.ini. Ensure sections [SectionName] and keys key = value are correct.
    • Use: /rehash command after manual edits to config.ini while tIRC is running.
    • Use: /save command to ensure in-client changes with /set are persisted.
    • Check: tIRC startup logs for any configuration parsing errors.

UI Glitches or Freezes

  • Symptom: Garbled text, unresponsive UI, incorrect window rendering.
    • Check: Terminal emulator compatibility. Some terminals handle Curses better than others.
    • Check: Terminal font and encoding (UTF-8 is recommended).
    • Check: If using SSH, network latency can sometimes affect Curses UIs.
    • Report: If reproducible, this might be a bug. Note your terminal, OS, and steps to reproduce.

Scripting Errors

  • Symptom: Scripts not loading, commands from scripts not working, errors in logs related to scripts.
    • Check: Script syntax. Run python -m py_compile path/to/your/script.py to check for basic Python errors.
    • Check: ScriptManager logs at startup for errors during script loading.
    • Check: Ensure the script has a create_script(api_handler) factory function.
    • Check: Ensure event handlers and command handlers have the correct signatures.
    • Use: self.api.log_info(), self.api.log_error() within your script for debugging.
    • Refer: To Scripting tIRC and Script API Reference.

DCC Transfer Failures

  • Symptom: DCC sends or gets fail to start or complete.
    • Check: [DCC] settings in config.ini (enabled, download_dir permissions, port range).
    • Check: Firewall settings on both your machine and router. DCC requires open ports or NAT traversal.
    • Try: Passive mode for sends (/dcc send -p ...) if active mode fails, especially if behind NAT.
    • Check: dcc_advertised_ip setting if you know your external IP and are behind NAT.
    • Check: logs/dcc.log for specific error messages.
    • Refer: To DCC Support.

Frequently Asked Questions (FAQ)

(This section can be expanded over time with actual FAQs)

  • Q: How do I auto-connect to a server and join channels on startup?

    • A: In config/tirc_config.ini, under your desired [Server.YourServerName] section, set auto_connect = true and list channels in channels = #chan1,#chan2. Only one server can have auto_connect = true.

  • Q: How do I use SASL authentication?

    • A: In your server configuration block, set sasl_username = your_account_name and sasl_password = your_sasl_password. Ensure the server supports SASL PLAIN (or other mechanisms if tIRC adds support for them).

  • Q: My script isn't loading. What should I do?

    • A: Check tIRC's startup logs for messages from ScriptManager. Ensure your script is in the correct scripts/ directory, has no syntax errors, and includes the create_script(api_handler) function. Check for any missing dependencies if your script uses external libraries.

If you cannot resolve an issue using these tips and the available documentation, please consider seeking help via the channels listed on the Support page.