Troubleshooting

Overview

Most ASD CLI issues fall into a handful of categories: installation problems, port conflicts, tunnel connectivity, or stale local state. This page walks through each scenario with concrete steps to diagnose and resolve the problem.

If you are new to ASD and have not set up your first tunnel yet, start with the Getting Started guide before returning here.

Command Not Found: asd

After installation, your shell cannot locate the asd binary.

On Linux and macOS:

# Reinstall with the official installer
curl -fsSL https://raw.githubusercontent.com/asd-engineering/asd-cli/main/install.sh | bash

If the installer completed successfully but asd is still not found, check that the install location is on your PATH:

echo $PATH

The default install location is ~/.local/share/asd/bin/. Add it to your shell profile if it is missing:

# For bash
echo 'export PATH="$HOME/.local/share/asd/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="$HOME/.local/share/asd/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

On Windows:

The installer places asd.exe at %LOCALAPPDATA%\asd\bin\asd.exe. If the PATH prompt was skipped during installation, the binary will not be found by name.

Option 1 — Run with the full path:

%LOCALAPPDATA%asdinasd --version

Option 2 — Add the directory to your PATH permanently (run in an Administrator PowerShell):

$installDir = "$env:LOCALAPPDATAasdin"
$path = [Environment]::GetEnvironmentVariable("PATH", "User")
[Environment]::SetEnvironmentVariable("PATH", "$path;$installDir", "User")

Restart your terminal after making PATH changes.

Port Already in Use

Another process is occupying the port you are trying to expose or that a built-in service needs.

Diagnose:

# Find what is using the port (Linux/macOS)
lsof -i :3000

# On Windows (PowerShell)
netstat -ano | findstr :3000

Resolve:

# Kill the process occupying the port
kill <pid>

# Or expose a different port instead
asd expose 3001

Built-in services like the web terminal (ttyd) and VS Code Server use dynamically assigned ports by default. If you have configured a fixed port in your .env file and it conflicts, either remove the fixed port setting to let ASD auto-assign, or stop the conflicting process.

Login Failures

If asd login does not complete successfully:

Browser does not open:

• On headless systems (SSH, containers, CI), ASD falls back to a device code flow automatically. You see a code like ABCD-EFGH and a URL — open the URL on any device with a browser and enter the code.
• If no fallback appears, check that your terminal supports launching URLs. Try running xdg-open https://example.com (Linux) or open https://example.com (macOS) to test.

Login completes but tunnels fail:

• Your subscription may not include tunnel access. Free plans support ephemeral tokens only. Check your plan at asd.host/pricing.
• Run asd auth whoami to confirm your credentials were stored.

OAuth callback error:

• Make sure your browser is not blocking pop-ups or redirects from asd.host.
• Try a different browser or use the device code flow by running asd login from a terminal without browser access.

Tunnel Not Connecting

Tunnel failures are typically caused by missing or expired credentials, or by network restrictions.

Step 1 — Check your authentication status:

asd auth status

If your credentials are missing or expired, re-authenticate:

asd login

Step 2 — Reset the tunnel state:

asd net expose reset

This clears local tunnel registration and forces a fresh connection on the next asd net apply --tunnel.

Step 3 — Verify your tunnel token:

If you are using token-based authentication (common in CI/CD), confirm that ASD_TUNNEL_TOKEN and ASD_TUNNEL_USER are set correctly in your .env file or environment.

Tunnel tokens are managed from the ASD dashboard at asd.host under Account > Tunnel Tokens. All paid plans include tunnel access — see Pricing for plan details.

Step 4 — Check for firewall or VPN interference:

ASD tunnels use outbound SSH on port 2223. Some corporate firewalls, VPNs, and restrictive Wi-Fi networks block non-standard SSH ports.

# Test if port 2223 is reachable
nc -zv eu1.tn.asd.engineer 2223

If the connection times out, try:

• Disconnecting from the VPN temporarily
• Switching to a different network (e.g., mobile hotspot)
• Asking your network administrator to allow outbound TCP on port 2223

Service Not Appearing in the TUI

When asd net does not show a service you expect, the service registry may be out of sync.

Quick fix — refresh health checks:

asd net refresh

Inside the TUI, you can also press Ctrl+R to refresh all service statuses.

Full fix — rebuild the registry:

rm .asd/workspace/network/registry.json
asd net apply

This removes the cached registry and regenerates it from your asd.yaml configuration.

Caddy Will Not Start

The local Caddy reverse proxy can fail to start if its state directory is corrupted or if another Caddy instance is already running.

Step 1 — Stop and clean Caddy state:

asd caddy stop
rm -rf .asd/workspace/caddy/

Step 2 — Start fresh:

asd caddy start
asd net apply

If Caddy still fails, check whether another Caddy process is occupying port 80:

lsof -i :80

Kill the conflicting process and try again.

Full Reset (Nuclear Option)

When multiple things are broken and individual fixes are not working, a complete workspace reset clears all local state without affecting your project files or configuration.

Warning: This stops all ASD-managed processes and removes all workspace state. Your asd.yaml, .env, and source code are not touched.

# Stop all ASD-managed processes
pkill -f "caddy run"
pkill -f "asd-tunnel"

# Remove all workspace state
rm -rf .asd/workspace/

# Reinitialize and apply configuration
asd init
asd net apply --caddy --tunnel

After the reset, run asd net to verify that all services show a green status.

Debug Mode

When you need more detail about what ASD is doing internally, enable debug logging by setting the ASD_DEBUG environment variable:

ASD_DEBUG=1 asd net apply

Debug mode produces verbose output for every step of the configuration process, including Caddy route generation, tunnel credential resolution, and health check results. This output is invaluable when filing bug reports.

Viewing Logs

ASD stores logs for its managed services in .asd/workspace/logs/. You can view them directly or through the CLI:

# View Caddy proxy logs
asd logs caddy

# View tunnel connection logs
asd logs tunnel

These logs capture request routing, tunnel connection events, and error traces. When troubleshooting intermittent issues, check the logs for patterns around the time the problem occurs.

Common Error Messages

Error	Cause	Fix
Missing username or password	ttyd credentials not set	Set TTYD_USERNAME and TTYD_PASSWORD in .env
Binary not found	Binaries not downloaded	Run asd init to re-download
ECONNREFUSED	Target service not running	Start your local service before exposing
401 Unauthorized	Invalid tunnel credentials	Run asd login or check your tunnel token
infinite recursion on tunnel URL	Credential registry empty	Run asd login to populate credentials

Getting Help

If the steps above do not resolve your issue:

• GitHub Issues: Report bugs and request features at github.com/asd-engineering/asd-cli/issues. Include the output of ASD_DEBUG=1 asd net apply and your platform details.
• Documentation: Browse the full reference at asd.host/docs.

Related Guides

• Getting Started — Step-by-step first tunnel setup
• CLI Command Reference — Detailed reference for asd expose and all other commands
• Configuration Reference (asd.yaml) — Project configuration reference