# Risoluzione dei problemi

## "spawn tmux ENOENT"

tmux non è installato o non si trova nel vostro PATH. Termbridge mostra questo errore, ma continua a funzionare senza avviare un terminale ([#4](https://github.com/inline0/termbridge/issues/4)); premete `Ctrl+C`, installate tmux e riavviatelo.

```bash
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux
```

## "spawn cloudflared ENOENT"

Il client tunnel di Cloudflare non è installato o non si trova nel vostro PATH. Serve solo per la modalità tunnel; le modalità diretta `--no-tunnel` e Daytona non richiedono cloudflared.

```bash
# macOS
brew install cloudflared
```

Per Linux, scaricate il programma da [cloudflare.com/downloads](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).

## Il tunnel non si avvia

Ecco alcune verifiche da fare (saltatele se usate la modalità sandbox diretta):

1. Verificate che cloudflared funzioni: `cloudflared --version`
2. Assicuratevi di poter raggiungere `https://trycloudflare.com`
3. Verificate che un firewall non blocchi le connessioni in uscita

Se il tunnel non si avvia, Termbridge mostra l'errore, arresta il proprio server e termina con stato 1. Non passa a una modalità solo locale e, per impostazione predefinita, il server resta in ascolto solo su `127.0.0.1`, quindi neanche gli altri dispositivi della vostra rete possono raggiungerlo. Le sessioni tmux create per quell'esecuzione restano attive ([#4](https://github.com/inline0/termbridge/issues/4)).

Per usare Termbridge senza il tunnel Cloudflare, eseguitelo dietro un proxy inverso o un tunnel di vostra scelta, usando `--no-tunnel --public-url <url>`.

## «429 Troppe richieste» da trycloudflare

Cloudflare applica limiti di frequenza ai tunnel senza account. Se visualizzate errori come `429 Too Many Requests`, provate a:

1. Attendere qualche minuto e riprovare
2. Verificare che non ci siano ancora processi `cloudflared` precedenti in esecuzione
3. Usare un token per un tunnel con nome (consigliato per l'uso frequente)

## Schermo vuoto o «Impossibile caricare i terminali»

Di solito significa che il browser non ha un cookie di sessione valido, ad esempio perché è stato aperto senza riscattare un link di condivisione o perché il tunnel URL è cambiato:

1. Verificate se il server locale è ancora in esecuzione
2. Controllate nella console del browser la presenza di errori 401/403
3. Riavviate Termbridge per ottenere un nuovo codice URL e QR

## Il terminale non mostra output

La sessione tmux potrebbe non essere in esecuzione:

```bash
# Check if sessions exist
tmux ls
```

Se le sessioni sono visibili ma il terminale è vuoto, provate a:
- Ricaricare la pagina
- Verificare che la shell supporti `TERM=xterm-256color`

## Il codice QR viene scansionato, ma la pagina è vuota

Il codice QR contiene un token monouso. Funziona una sola volta e solo entro 90 secondi dall'avvio di Termbridge. Un link già usato o scaduto restituisce `invalid token`.

Soluzione: riavviate Termbridge per generare un nuovo codice QR e scansionatelo subito.

## Errori di node-pty relativi a spawn-helper

Termbridge prova a risolvere automaticamente il problema, ma se visualizzate errori di autorizzazione:

```bash
chmod +x node_modules/node-pty/prebuilds/**/spawn-helper
```

## Il problema persiste?

Aprite una segnalazione su [github.com/inline0/termbridge](https://github.com/inline0/termbridge/issues) includendo:
- Il vostro sistema operativo e la versione Node.js
- Il messaggio di errore
- I passaggi per riprodurre il problema