Troubleshooting

Things that go wrong, and the fix

Common problems, in the order users actually hit them.

If your problem is voice-related, also see Voice & Push-to-Talk.

The plugin did not load. Check:

The folder is at X-Plane/Resources/plugins/NextATC/ (exactly this path).
The folder name was not changed.
On macOS, Gatekeeper may have blocked the binary. Re-run the bundled installers/Install - macOS.sh (it strips the com.apple.quarantine attribute), or open System Settings -> Privacy & Security and allow the blocked X-Plane plugin.

Then open X-Plane/Log.txt and search for NextATC. The log normally says exactly why a plugin did not load.

No ATC actions appear in the Radio Log#

Walk down this list:

The plugin is started (Plugins -> NextATC -> Start plugin).
The aircraft has electrical power. The COM radio is on.
You are tuned to the right frequency for the current phase. Delivery for IFR clearance; Ground for start/pushback/taxi; Tower for takeoff and landing; Approach/Center in the air.
The Frequency Box is closed, or the Radio Log has focus. Click on the Radio Log if Handoff keeps tuning a frequency.
Radio Log -> Enabled is on in Options. Max visible lines is at least 2.

Handoff tunes a frequency instead of confirming a readback#

By default the Frequency Box has priority when it is open. Close it, or click the Radio Log to move focus, then press Handoff again.

If you want frequency priority back, reopen the Frequency Box with NextATC/frequency_selector_toggle.

The departure runway or SID is not the one I expected#

NextATC picks the runway from airport data, current wind, airport flow, your aircraft position, and plugin logic. It may not match the ATIS of an online network or a third-party tool.

Choose Override departure runway in the flight plan dialog before filing; the following departure dialog selects the SID for that fixed runway. Arrival runway and STAR selection remain in the Arrival Runway dialog. See Departure and Arrival.

No SID or STAR is found#

Possible reasons:

The selected runway has no published SID/STAR for your route endpoint.
Your cruise level is outside the procedure's restrictions.
The navdata is out of date or incomplete.

Workarounds:

Use Don't use SID / Don't use STAR.
Pick a different first/last enroute fix that connects to a published procedure.
Update the plugin navdata folder. See Navdata.

The taxi guide does not appear#

Enable Draw taxi guide on ground in Options. The guide only appears when the plugin has a valid ground route for the current phase. Some airports have incomplete taxi networks; the plugin falls back to centerline data where possible, but not every scenery package exposes usable route data.

ATC keeps correcting my altitude#

Two common causes:

Altimeter setting: above the transition altitude you should be on standard pressure (1013/29.92). Below the transition level you should be on the local QNH/altimeter setting.
SID/STAR restrictions: if you turned on Respect SIDs and STARs restrictions, the controller expects you to honour procedure altitude windows.

TTS is silent#

Walk down:

Read ATC messages (TTS) is on in Options.
Your operating system has at least one installed voice.
Voice Roles is valid if you set custom voices (no typos in voice names).
Azure key and region are valid if Speech engine is Microsoft Azure. See Azure Setup.
Your sound output device is not muted.

Voice recognition does not pick anything up#

See Voice & Push-to-Talk. The short version:

The microphone works in another app.
The selected recognition model is downloaded in Options.
The PTT command is bound to a key.
You hold the key while you speak.

When in doubt, click Readback with the mouse. Voice is optional.

I cannot see any traffic on the Nav Display#

NextATC shows traffic that is published over X-Plane's TCAS datarefs, plus its own synthetic traffic when the Traffic engine is on. Without a publisher (X-Plane AI, LiveTraffic, XSquawkBox, or NextATC's own synthetic traffic), the map markers and Airport board are empty by design. See Traffic.

Random flight does not start#

Check the random-flight region filters in Options. At least one region must be enabled, and the selected region pool must contain airports suitable for the generated flight. You can always file manually from the flight plan dialog if you want to choose the route yourself.

The plugin window is on the wrong monitor#

Open Options -> NextATC Windows Monitor and pick the target monitor. Use Auto / Primary if you only have one screen.

Where are the settings stored?#

X-Plane/Resources/plugins/NextATC/settings.ini
X-Plane/Resources/plugins/NextATC/traffic_settings.ini

You can edit them with any text editor while X-Plane is closed. Use the voice role controls in Options -> Voice to configure voices.

Where are the logs?#

X-Plane/Log.txt

When reporting a bug, include the airport, runway and phase of flight, with a screenshot when useful. The built-in reporter prepares current-flight diagnostics. A web bug report requires the affected readable Log.txt; review it for private information before uploading. See Bug reports and feature requests.

ATC text appears but there is no voice#

Check these points and note the results for a report:

Read ATC messages (TTS) is on, and which Speech engine is selected.
In the voice roles window of that engine, press the ATC voice test: Test current ATC for Kokoro and Piper, Test current ATC voice for Azure and Windows voices. Note whether it is audible.
The [Radio] section of settings.ini holds the related non-secret values: isSpeechActivated, ttsEngine, azureTtsOn, disableVoiceOnReadBack, xAtcChatterCompatibility.

X-Plane slows down, stutters or loses FPS#

Performance, lag, stutters, slowdowns and frame rate drops can come from several NextATC features. They add up, so check each one; the simplest test is to turn them off one at a time and watch the frame rate.

Built-in traffic. The synthetic traffic engine can be a significant load, growing with the number of aircraft. In Traffic Options... lower Traffic amount, turn off Draw 3D aircraft to keep the aircraft only on TCAS and the Nav Display, or turn off Traffic engine.
Local voices (Kokoro and Piper). Every spoken transmission, including traffic radio chatter, is generated on your CPU. This causes short dips each time ATC or traffic speaks, more noticeable at busy airports. Piper with Light models enabled (the default) is the lightest local option, about eight times less CPU than high-quality Piper models; Kokoro's Compact model (114 MB instead of 325 MB) reduces its load less. Make sure the selected models are downloaded, choose Microsoft Azure in Speech engine (generated in the cloud), or turn off Read ATC messages (TTS) to keep text only. On macOS and Windows local speech already runs at a lower priority than X-Plane.
Voice recognition (Whisper). Transcribing your microphone audio uses the CPU, or the GPU with Use GPU acceleration (Metal on supported Apple silicon Macs, NVIDIA CUDA on Windows). Larger models are slower: use Whisper Base English, enable Use GPU acceleration where available, or turn off AI Voice Recognition (Experimental).
AI phrase generation (Gemini). The wording is generated in the cloud, so it does not run a language model on your computer.

If dips happen exactly when ATC speaks, start with the local voice settings; if they are constant, start with traffic.