Troubleshooting

Portless Not Found

Symptom: pier fails to start an app command and mentions portless.

npm install -g portless

Bridge Unreachable in Extension

1. Run pier bridge status
2. Run pier doctor
3. Confirm extension WebSocket URL and token match setup output
4. Use Test Bridge in extension settings

Token Errors or Authentication Failures

• Re-read token from pier doctor and paste it again in extension settings
• Reload localhost tabs after saving settings

Terminal Opens in Wrong Directory

Inspect mappings:

pier map list
pier map where myapp.localhost

Re-add mapping if needed:

pier map add myapp.localhost /correct/path

node-pty or Terminal Spawn Issues

Pier falls back to child_process pipes when PTY initialization fails, but interactive behavior may be reduced.

• Check pier bridge logs
• Check pier doctor
• Confirm shell path in config (bridge.shell) is valid

Extension Loads But Shortcut Does Nothing

• Confirm page host is localhost, 127.0.0.1, ::1, or *.localhost
• Check extension is enabled
• Reload the page after updating extension settings