Troubleshooting and FAQ

Troubleshooting and FAQ

[COMMS] Bill (Eng): Have you tried turning it off and on again? No, really. That's step one.

The bridge isn't running / "[bridge]" errors in the chat

The plugin starts the bridge when KSP starts. If the chat says it can't reach the bridge:

1. Check GameData/KSPChatBridge/PluginData/bridge.cfg: bridge_dir must point at the folder with run_bridge.py, and python must work (try the full path to python.exe).
2. Open http://127.0.0.1:8765/health in a browser. If you get a short JSON answer, the bridge is up.
3. Start it by hand to see its error messages: open a command prompt in the bridge folder and run python run_bridge.py serve.
4. Look at logs/bridge.log in the bridge folder. It's the first place any problem shows up.
5. Missing packages? Run python -m pip install --user -r requirements.txt again.

"Port 8765 already in use"

Another copy of the bridge is already running, which is usually fine: the plugin uses whichever one answers. If it's an old copy that's stuck, close it (end the python process in Task Manager) and restart KSP or run start_bridge.cmd. The plugin always talks to port 8765, so don't move the bridge to a different port.

Can't connect to kRPC

• Is the kRPC server running in KSP? Open its window and press Start, and turn on auto-start.
• Did KSP ask about a new client connection? Turn on auto-accept new clients, or click Allow.
• Ports: the bridge expects 127.0.0.1, RPC 50000, stream 50001. If you changed them in kRPC, set KRPC_ADDRESS, KRPC_RPC_PORT and KRPC_STREAM_PORT (see Settings).
• kRPC 0.6.x is what's tested. Python krpc should be 0.6.0 too (requirements.txt pins it).

The AI says it did something, but nothing happened

Some models, especially small local ones, describe an action instead of actually calling the tool. The bridge catches this: it asks the model again to actually do it, and if it still only talks, the reply ends with (no action taken). Fixes:

• Use the direct Captain's Orders for everyday things. They don't need the AI at all.
• Use a model with reliable tool calling: qwen/qwen3.5-9b or google/gemma-4-e4b locally, or a cloud backend.
• Avoid models without tool support.

KSP stutters, or my PC runs out of memory

KSP and a local model share your graphics card. A 9B model needs about 6 GB of graphics memory, gemma-4-e4b about 4.7 GB. Options:

• load a smaller model (/model gemma or pick one in LM Studio),
• unload the model when you're not chatting (direct orders still work),
• or use a cloud backend (Groq and Gemini have free tiers).

Cloud: "rate limit hit" or "rejected the API key"

Rate limits: the bridge waits (up to 30 s) and retries once, then tells you. Groq's free tier hits its tokens-per-minute cap fastest. Switch backend in AICS -> Settings or with /ai. A rejected key means the key is wrong or expired: paste a new one in AICS -> Settings.

My prop plane or helicopter won't produce thrust

Look at the rotors' part menus. The usual culprits are Brake 100, Torque Limit 0 or Motor disengaged. The pre-flight check fixes these before takeoff and says so in the chat (Pre-flight: ... Brake was 100 -> released (0)). If you're flying by hand without an autopilot, set them yourself or say props on / torque max.

If the bridge says it can't read the rotor fields, update to the current release: kRPC 0.6 changed how part fields are read, and older bridge versions couldn't read Breaking Ground rotors.

Rotors only count with blades attached. A bare hub isn't a propeller.

My craft was detected as the wrong type

The bridge decides plane / helicopter / rocket from the parts: lift rotors pointing up = helicopter, real wings with jets or props = plane, and so on. A craft with one lift fan and real wings but no side props or tail rotor is treated as a plane. The detected layout is in logs/bridge.log (look for heli: or props: lines). If it's wrong, please open an issue with the craft file.

The first landing slowed down weirdly at altitude

That's the one-time slow-flight test to measure the stall speed. Later landings of the same craft skip it.

The chat window's keyboard ate my controls

While the chat input has focus, KSP's keys are locked. Click anywhere outside the window.

The crew won't shut up

/crew chatter off. They'll sulk, quietly.

[INTERCOM] Bob (Sci): Rude.

Does it work without MechJeb?

Yes. Planes, props, helicopters, the crew, the dashboard, Flight Plans with plane steps, science and power all work without it. Ascent, maneuvers, docking and the MechJeb-guided landings need MechJeb2 + kRPC.MechJeb.

Does it work on Linux or Mac?

It's built and tested on Windows. The plugin is plain KSP 1.12, and the bridge is Python, so it may work elsewhere, but the helper scripts are PowerShell and nobody's tested it. Reports welcome.

Does it phone home?

No. The bridge only talks to KSP (kRPC on your machine) and to the AI backend you choose. With LM Studio, nothing leaves your PC. Your keys stay in .env.

Where are the logs?

• Bridge: logs/bridge.log in the bridge folder (rotating, 1 MB x 3) and logs/sessions-*.jsonl (one line per chat turn).
• Plugin: KSP's own KSP.log, lines starting with [KSPChatBridge].

Include both when you report a bug. Check them for anything private first.