↓ Skip to main content
TantoC2 Documentation
  1. Documentation/
  2. Reference/

Troubleshooting

Table of Contents

Teamserver Fails to Start
#

Port already in use
#

1

ss -tlnp | grep 8443

Change the port in config or stop the conflicting process.

Permission denied on port < 1024
#

Use a port >= 1024 or run with appropriate capabilities.

Missing dependencies
#

Ensure all wheels are installed:

1

pip install dist/*.whl

Cannot Connect from CLI
#

  • Verify the URL includes the protocol: connect http://localhost:8443
  • With self-signed certificates, the CLI client may need to skip TLS verification
  • Check that the teamserver is running and the port is accessible

Agent Not Appearing
#

  • Verify the listener is started (not just created): listeners list should show running
  • Check that the agent’s callback URL matches the listener’s host:port
  • Review teamserver logs for registration errors
  • Ensure the correct engagement is activated

Authentication Errors
#

  • Rate limiting: Auth endpoints trigger rate limits after repeated failures. Wait and retry.
  • Token expiration: Use the refresh token endpoint or re-login.
  • Force-logout: Invalidates all tokens. Re-login required.

Engagement Database Errors
#

  • If a database appears corrupted, restore from the most recent archive
  • Schema migrations run automatically. If a migration fails, a pre-migration backup is created in the same directory

Background Services Not Running
#

  • Background services start automatically with the teamserver
  • Check logs for errors
  • Verify interval configurations are reasonable (not 0 or extremely large)

Log Redaction Hiding Debug Information
#

Temporarily disable:

1

export TANTOC2_LOG_REDACTION_ENABLED=false
Re-enable before operational use.

Agent Shows as Dormant or Dead
#

Agent status transitions are based on missed check-ins relative to beacon interval:

  • Dormant: Missed 3x beacon interval
  • Dead: Missed 10x beacon interval

Check:

  • Is the agent process still running?
  • Can the agent reach the listener (network path)?
  • Is the listener still running?

Build Fails
#

  • Check build packages to verify the package exists
  • Check build templates <pkg> for valid template names
  • Ensure --kill-date is a future date
  • Review teamserver logs for detailed error messages

File Transfer Hash Mismatch
#

If hash_verified is false:

  • The file may have been modified during transfer
  • Check with files info <agent-id> <transfer-id> for details
  • Retry the transfer