Feilsøking

Sjekk maskinen

nav-pilot doctor              # konfig, installasjon, hooks, klienter, cplt og git
nav-pilot config validate     # bare konfigfila: syntaks, nøkler og verdier
nav-pilot mcp list            # MCP-servere som ikke virker, og kommandoen som retter det
nav-pilot alpha local doctor  # bare egen LLM-server (local_endpoint)

doctor endrer ingenting, og hvert problem kommer med kommandoen som løser det. Den avslutter med kode 0 også når den finner noe, så les linjene med «Solution».

alpha local doctor sjekker verktøykall, logprobs, kontekstlengde og tid til første token på serveren du kjører selv. Kontekstsjekken kan ta minutter på en CPU. For modellen nav-pilot setter opp på Mac bruker du nav-pilot alpha local status.

Finner du en feil, meld den med nav-pilot feedback. Den åpner et issue i navikt/copilot med versjon og systeminformasjon fylt inn. Ingenting går ut før du sender inn issuet.

Når en MCP-server ikke virker

Start med nav-pilot mcp list. Den endrer ingenting. Øverst står det som hindrer serverne du har slått på, med kommandoen som retter det: et navn organisasjonens policy blokkerer, en host eller localhost-port cplt stopper, en pakkekjører som mangler, eller en server registeret har tatt ut.

nav-pilot mcp list                            # problemer først, så serverne i registeret
nav-pilot mcp enable <navn>                   # slå på i Copilot CLI og opencode
nav-pilot mcp enable <navn> --client copilot  # bare i én klient
nav-pilot mcp disable <navn>                  # slå av, og steng hostene bare den trengte

Navnet er hele navnet i registeret eller delen etter siste skråstrek, som figma-mcp. Start en ny økt etterpå, så laster klienten serveren. Hvilke servere som finnes, står under MCP-registeret.

Verktøy som er slått av

Registeret gir hvert verktøy en risikoklasse. enable slår på read og write. Av står external, som handler i et annet system (en issue, en PR, en fil i Figma), og host-exec, som kjører på maskinen din utenfor cplt-sandkassen. I en terminal viser enable alle verktøyene med klasse, og du velger selv. Et host-exec-verktøy må du i tillegg si ja til.

nav-pilot mcp enable <navn> --tools <a,b>   # nøyaktig disse verktøyene
nav-pilot mcp enable <navn> --all-tools     # alle, også dem serveren legger til senere

Har du serveren fra før, lar enable oppføringen være som den er, med mindre du gir --tools eller --all-tools. Da endres bare verktøyene.

IntelliJ og verktøy utenfor sandkassen

IntelliJ-serveren har verktøy som execute_terminal_command, som kjører i IntelliJ og ikke i sandkassen. Et slikt verktøy slår du bare på med --allow-host-exec. Er det på, advarer mcp list før du åpner localhost-porten til IntelliJ, fordi agenten da når verktøyet. Rettingen den foreslår, slår av verktøyene som kjører utenfor sandkassen først, og åpner porten etterpå.

GitHub-serveren leser bare

GitHubs MCP-server får det skrivebeskyttede endepunktet. Velger du et verktøy som skriver til GitHub, som issue_write, bytter nav-pilot til det fulle endepunktet. Da kan agenten skrive til GitHub gjennom MCP, forbi vakta cplt har på gh. mcp list merker det med full endpoint og gir kommandoen som tar deg tilbake.

Hoster i sandkassen

Når du starter nav-pilot i en terminal, spør den om cplt skal slippe gjennom hostene serverne dine trenger. Hostene hentes fra registeret, aldri fra MCP-konfigen din: serverens adresse, og sandboxHosts for andre hoster den trenger, som innloggingen til Figma. Enter betyr nei. Uten terminal spør nav-pilot ikke, og slipper bare gjennom hoster du alt har sagt ja til.

Har du sagt nei, spør ikke nav-pilot igjen ved oppstart. Kjør nav-pilot mcp enable <navn> i en terminal, så får du spørsmålet på nytt. Med mcp_hosts = off spør den aldri.

Satt du strict med nav-pilot, legger nav-pilot hostene du sa ja til i sin egen host-liste. Har du laget lista selv med proxy.allowed_domains, gjør den ikke det. Da viser mcp list at cplt stopper hosten, og du legger den til selv:

cplt config set allow.domains <host>

Mangler registeret en host serveren trenger, må oppføringen i registeret rettes. Se Få en server inn i registeret.

Feil fra cplt

Stopper sandkassen noe agenten skal gjøre, slå opp feilmeldingen i Feil i sandkassen. Trenger repoet mer enn standard, se Sett opp cplt i et repo.

Se hva cplt blokkerer

cplt stopper ting på to steder. Proxyen stopper nettverkskall til hoster på internett, og skriver dem til stderr. Kjernen stopper filer, programmer og localhost, og det står bare i verktøyet som feilet, se Filer, programmer og localhost.

Med en host-liste, som på strict satt med nav-pilot, viser proxyen blokkeringene uten at du gjør noe. På standard uten egen proxy.allowed_domains tier den om dem: treff i cplts egen blokkliste, stengte porter, hoster som peker til private eller link-local IP-adresser, og oppslag som feiler. Vil du se dem, sett nivået selv:

cplt config set proxy.log_level blocked

Vil du ha en fil å lese etterpå, bruk proxy.log_file. Den dekker det proxyen avgjør, ikke det gh- og git-vakta avgjør. Sikkerhetsnivåene står i referansen.

Filer, programmer og localhost

Meldingen er Operation not permitted, EPERM eller connect EPERM 127.0.0.1:…, og proxyloggen er tom. Spør cplt om det som feilet. Svaret sier om det er tillatt eller stoppet, hvorfor, og hva som åpner det:

cplt check path ~/.gradle/gradle.properties   # får agenten lese fila?
cplt check path --write ~/.cache/verktøy       # får agenten skrive der?
cplt check net repo.adeo.no                    # slipper proxyen gjennom hosten?
cplt check exec docker                         # får agenten kjøre programmet?

cplt check exec sjekker om programmet får starte, ikke hvilke filer det leser etterpå. For localhost gjelder allow.localhost, ikke --allow-port, se Det stakken din trenger.

På macOS kan du se alt kjernen stopper mens agenten jobber. Starter du cplt selv, bruk --show-denials. Linjene kommer i samme terminal som agenten:

cplt --show-denials

Starter du agenten med nav-pilot, kjør det samme filteret i en annen terminal mens agenten jobber:

log stream --style compact --info   --predicate 'eventMessage CONTAINS "Sandbox" AND eventMessage CONTAINS "deny"'

En linje ser slik ut: Sandbox: cat(85111) deny(1) file-read-data /Users/deg/.npmrc. Loggen tar med andre programmer også, så se etter navnet på det som feilet. På Linux finnes ikke loggen, fordi Landlock ikke logger det den stopper.

Når den lokale modellen henger

status skiller «treg» fra «død».

nav-pilot alpha local status
# står det hung: nav-pilot alpha local restart

mlx-lm henger seg opp på samtidige forespørsler, så serveren nav-pilot starter, tar én om gangen. Opptil åtte venter i kø i inntil ti minutter hver. Er køen full, eller ventetiden ute, svarer serveren 503 og sier at den er opptatt. Vent litt og prøv igjen. Startet serveren før du oppgraderte nav-pilot, kjør nav-pilot alpha local restart.

nav-pilot avslutter en runde, og sier fra i økten, hvis modellen gjør det samme verktøykallet fire ganger på rad med samme resultat, eller åtte ganger på rad uansett resultat. Det er en vakt mot at modellen står fast, ikke en feil i koden din. Grensene endrer du med local_loop_guard.

Går modellen tom for minne, for eksempel på en lang prompt, avslutter serveren seg selv. Neste økt sier generation thread died, most likely out of memory, med stien til tracebacken. Start den igjen med nav-pilot alpha local restart. Skjer det igjen, velg en modell med kortere kontekst.

Starter du serveren på nytt midt i en økt, må du starte økten på nytt også. Den gamle er bundet til serveren som forsvant.

Si fra med nav-pilot feedback om noe henger, om en endring kompilerer men er feil, eller om ventetiden ikke er verdt det.

Serveren vil ikke starte etter en omstart

Minnegrensen i macOS nullstilles når maskinen starter på nytt. start spør da om å heve den med sudo, og trenger passordet ditt. Svarer du nei, eller kjører den uten terminal, som ved automatisk start, stopper den og skriver kommandoen du må kjøre selv:

sudo sysctl -w iogpu.wired_limit_mb=<MB>   # tallet står i feilmeldingen
nav-pilot alpha local start

Sier start at vektene ikke finnes på maskinen, kjør nav-pilot alpha local init. Den laster dem ned og starter serveren.