> ## Documentation Index
> Fetch the complete documentation index at: https://docs.czautoz.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Issues

> Solutions to the most common problems encountered with CZ Autoz Helicopter.

<Note>
  **Start here before anything else.** CZ Autoz Helicopter generates its own dedicated log files — these will tell you exactly what is wrong far faster than anything else. See [Logging & Diagnostics](#logging--diagnostics) below for the full list and what each file contains.
</Note>

***

## Installation & Whitelisting

<AccordionGroup>
  <Accordion title="Helicopters don't work / controls are unresponsive">
    The most common cause is an **IP not being whitelisted**. The first thing to do is check the whitelist status log — it tells you exactly what the mod found:

    ```
    $profile:\CZAutoz_Heli_whitelist_status.log
    ```

    The log will show your server's detected IP and port, the whitelist result (`WHITELISTED` or `NOT WHITELISTED`), and the exact reason if it failed. Common reasons shown in the log:

    * **IP not registered** — go to [#ip-whitelisting](https://discord.com/channels/768275677480353824/1168185657672356011) and submit your IP via the bot
    * **Port mismatch** — the port in the log doesn't match what was registered; re-whitelist with the correct port
    * **API unreachable** — the mod couldn't reach the whitelist service; check your server's outbound internet access, check `CZAutoz_Heli_whitelist_debug.log` for connection details, and verify the service is online at [status.czautoz.co.uk](https://status.czautoz.co.uk)
    * If your server IP has changed (new host, new instance), re-whitelist the new IP via the bot
    * After whitelisting, **restart the server** for it to take effect
  </Accordion>

  <Accordion title="Config files are not being generated">
    Config files are written to `$profile:\CZAutoz_Heli\` on the **first server start** after the mod is loaded.

    * Confirm the mod is correctly added to your server's `-mod=` startup parameter
    * Confirm the mod is loading successfully — check your RPT log for any mod load errors
    * Make sure the server profile directory is writable
    * Try a full server restart (not a crash recovery restart)
  </Accordion>

  <Accordion title="Mod loads but helicopters are not appearing in game">
    Helicopters are not added to loot automatically — you need to add them to your server's economy:

    * Add helicopter classnames to your `types.xml`, trader config, or event spawner
    * All spawnable classnames are listed on the [Helicopter Overview](/helicopters/overview#all-spawnable-classnames) page
    * After editing `types.xml`, restart the server for changes to take effect
  </Accordion>

  <Accordion title="Helicopters don't persist / disappear after a restart">
    As of **v0.2.1** the helicopters are built on DayZ's native **CarScript** base class, so they are covered by DayZ's native vehicle Central Economy root automatically — **no manual persistence setup is required.** Helicopters persist across restarts out of the box.

    * A manual `cfgeconomycore.xml` `<rootclass>` entry is **no longer required** as of v0.2.1
    * **Upgrading from v0.2?** v0.2 was built on the **Transport** base class and required a manual `<rootclass name="CZAutoz_Helicopter_Script" act="car" reportMemoryLOD="no" />` entry in `cfgeconomycore.xml`. Remove that line — it is no longer needed.
    * **Wipe existing helicopter persistence once** when updating to v0.2.1, as the save format changed with the base-class migration.

    See the [Persistence — No Setup Required](/getting-started/setup) step in the setup guide for full context.
  </Accordion>
</AccordionGroup>

***

## Engine & Battery

<AccordionGroup>
  <Accordion title="Cannot start the engine — no start action appears">
    The engine start action requires a **charged CZ\_HelicopterBattery** in the helicopter's battery slot.

    * Check the helicopter's inventory for a `CZ_HelicopterBattery` item in the dedicated battery slot
    * If the battery is present but has **zero charge**, it needs to be recharged or replaced
    * If no battery is present at all, add `CZ_HelicopterBattery` to your `types.xml` so it can spawn
    * To disable the battery requirement entirely: set `battery.startDrain = 0` in the helicopter's JSON config
  </Accordion>

  <Accordion title="Battery drains very quickly">
    Battery drain is controlled by three settings in the `battery` section of the helicopter's JSON config:

    | Setting              | Effect                                                     |
    | -------------------- | ---------------------------------------------------------- |
    | `battery.startDrain` | Drained per engine start/stop (default: `10`)              |
    | `battery.lightDrain` | Drained per second with lights on (default: `2.0`)         |
    | `battery.chargeRate` | Recharged per second while engine running (default: `5.0`) |

    Battery max charge is 500 units. Increase `battery.chargeRate` or reduce drain values to extend battery life.
  </Accordion>

  <Accordion title="Engine won't start even with a charged battery">
    * Confirm the battery is in the correct **HelicopterBattery slot** (not general cargo)
    * Make sure the battery charge is **greater than 0** — a battery at exactly 0 charge will not work
    * If the battery is correct and charged but the engine still won't start, check whether the server is whitelisted — an unwhitelisted server disables all mod features including engine start. Open `$profile:\CZAutoz_Heli_whitelist_status.log` to confirm the whitelist result
  </Accordion>
</AccordionGroup>

***

## Flight & Physics

<AccordionGroup>
  <Accordion title="Helicopter feels too heavy / hard to lift off">
    Increase `flight.liftMultiplier` in the helicopter's JSON config. Each helicopter has a different default:

    | Helicopter       | Default Lift |
    | ---------------- | ------------ |
    | MD500 Civilian   | 2.6          |
    | MH-6 Little Bird | 2.8          |
    | SA342M Gazelle   | 2.7          |
    | UH-1H Iroquois   | 3.3          |
    | MH-60L Blackhawk | 4.3          |
    | AW101 Merlin     | 4.3          |

    Try increasing by 0.2–0.5 increments and restarting the server to test.
  </Accordion>

  <Accordion title="Controls feel sluggish or unresponsive">
    Increase `control.b2tRampRate` for snappier control response. Lower values = smoother/more sluggish, higher = more direct.

    Also check `control.pitchStrength`, `control.bankStrength`, and `control.yawStrength` — these can all be increased independently.
  </Accordion>

  <Accordion title="Helicopter spins out of control after tail rotor damage">
    This is intentional behaviour when the tail rotor is destroyed. To reduce the severity:

    * Lower `tailRotorFailure.spinRate` (degrees per second of uncontrolled yaw)
    * Lower `tailRotorFailure.descentRate` (forced descent rate in m/s²)
    * Or disable tail rotor damage entirely: set `damage.zones.rotor2 = 0`
  </Accordion>

  <Accordion title="Autohover X key does nothing">
    Check `features.autoHoverEnabled` in `mod_config.json` — if this is set to `0`, Autohover is disabled server-wide. Set it to `1` and restart. Autohover is bound to **X** on the keyboard by default and is rebindable in the controls settings.
  </Accordion>
</AccordionGroup>

***

## Refuelling

<AccordionGroup>
  <Accordion title="Refuel action won't appear">
    The refuel action has several requirements — all must be met for it to show:

    * **Hold a gasoline container** — must be in your hands (e.g. Jerrycan). Only gasoline-type fuel is accepted; other liquid types will not work
    * **Look at the fuel refill point** on the helicopter model — the action appears on a specific component on the airframe, not just anywhere near the helicopter
    * **Within range** — you must be within `fuel.refuelDistance` metres of the refill point (default 5.0 m)
    * **Tank not already full** — the action won't appear if the helicopter's fuel is at 100%
    * **Container not ruined** — a ruined container cannot be used

    <Note>
      No jerry can? A helicopter can also be **pump-refuelled** at a working map fuel station (vanilla, Enoch, or a Simple Gas Pump) — fly or push it up to the pump and use the built-in refuel action, which fills at a faster rate.
    </Note>
  </Accordion>
</AccordionGroup>

***

## Repair & Damage

<AccordionGroup>
  <Accordion title="Cannot repair the helicopter / repair action not appearing">
    All repairs require every one of the following conditions:

    1. **HelicopterRepairKit held in hands** — must be actively held, not in inventory or backpack
    2. **Engine off** — or the main rotor must be fully destroyed (a destroyed main rotor unlocks repairs even if the engine is still spooling down)
    3. **Rotor spool below 50%** — the rotor must have slowed to below half speed before repairs are available
    4. **Helicopter within 5 m AGL** — must be on or very close to the ground
    5. **Player must be standing** — crouched or prone stances block the repair action
    6. **Proximity** — main/tail rotor repairs require you within 3 m of the rotor; all other zones within 5 m

    If all conditions are met and the action still doesn't appear, confirm `CZ_HelicopterRepairKit` is in your `types.xml` and spawning in the world.
  </Accordion>

  <Accordion title="Helicopter takes damage too easily / is too fragile">
    Adjust these settings in the `damage` section of the helicopter's JSON config:

    | Setting                 | Effect                                                 |
    | ----------------------- | ------------------------------------------------------ |
    | `damage.contactCoef`    | Lower = tougher airframe (less damage per impact)      |
    | `damage.crashThreshold` | Higher = harder hits needed before heavy damage occurs |

    To make a helicopter completely invincible, set all damage zones to `0` under `damage.zones`:

    ```json theme={null}
    "zones": {
      "chassis": 0,
      "body": 0,
      "engine": 0,
      "fuel": 0,
      "rotor1": 0,
      "rotor2": 0
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Cabin Mode

<AccordionGroup>
  <Accordion title="Character snaps / teleports repeatedly when moving to the cabin in flight">
    **Known issue — Cabin Mode is still being reworked and is now disabled by default (v0.2.4).** Moving to the cabin while the helicopter is **moving, hovering, or in flight** does not yet hold the pilot/co-pilot inside the cabin correctly (snapping/teleporting, or a stuck falling animation).

    * As of **v0.2.4**, `features.cabinModeEnabled` **defaults to `0`** — first-time and regenerated configs disable it automatically. **Please keep it disabled** until a future hotfix completes the rework
    * **Existing servers:** set `cabinModeEnabled = 0` in `mod_config.json` to hide the action and avoid the issue entirely
    * **Seat Exit Free Walk** and **Walk-On Linking** (cabin passengers, AW101 Merlin) are engine-native and were never affected
  </Accordion>

  <Accordion title="Move to Cabin action is not appearing">
    * Cabin Mode is only available on the **UH-1H Iroquois** and **MH-60L Blackhawk**
    * You must be seated as **pilot or co-pilot** — cabin passengers use the standard get-out action which exits them into the interior directly, so they do not have or need this action
    * As of **v0.2.4** `features.cabinModeEnabled` **defaults to `0`** (Cabin Mode is being reworked), so the action will not appear unless an admin enables it. We recommend leaving it **off** until a future hotfix — it reappears if `cabinModeEnabled` is set to `1`
  </Accordion>

  <Accordion title="Re-enabling Cabin Mode">
    Cabin Mode ships **OFF by default as of v0.2.4** while it is being reworked — we recommend leaving it disabled until a future hotfix. If you do want to turn it on, set `features.cabinModeEnabled` to `1`: from the in-game **Admin Panel** it applies **live** (no restart), or edit `mod_config.json` directly and restart the server.
  </Accordion>
</AccordionGroup>

***

## Configuration

<AccordionGroup>
  <Accordion title="Config changes are not taking effect">
    Changes made in the in-game **Admin Panel** apply **live** — they update every spawned helicopter and connected player instantly, no restart or reconnect (since v0.2.3). Only **direct edits to the JSON config files** need a server restart, since those are read on startup.
  </Accordion>

  <Accordion title="Config values after a mod update">
    Since **v0.2.3**, a mod update **migrates your configs in place** — new keys are added, removed keys cleaned up, and all your custom values are kept. It is triggered by the `version` field stored in `mod_config.json` changing.

    * Your originals are **backed up first** to `$profile:\CZAutoz_Heli\Backups\v<oldversion>_<date>\` before any migration touches a file
    * Only when first moving from **v0.2.2-or-earlier** onto a v0.2.3+ build might a one-time re-apply be needed
    * **Do not manually edit the `version`** field in `mod_config.json` — let the mod set it
  </Accordion>

  <Accordion title="New config keys from a mod update are missing">
    Since **v0.2.3** a mod version update **migrates configs in place**, so new keys are added automatically while your existing custom values are kept. If new keys are still missing after a server restart, check your RPT log for errors during config loading.
  </Accordion>
</AccordionGroup>

***

## Mod Compatibility

<AccordionGroup>
  <Accordion title="Vehicle 3PP / 3rd-person camera mod won't switch the helicopters to 3rd person">
    As of **v0.2.1** the helicopters are **CarScript** vehicles, so 3rd-person camera mods like **Vehicle 3PP** now apply their **whitelist** to them (under the old Transport base they bypassed it entirely and always showed 3rd person). If your helis are stuck in 1st person, they just need adding to the 3PP whitelist:

    * Open `$profile:3PPVehicleWhitelist.json`
    * Add `CZAutoz_Helicopter_Base` to the `Whitelist` array — this one base class covers **all** CZ Autoz helicopters via inheritance
    * Or leave the `Whitelist` array **empty** to allow 3rd person on all vehicles
    * 3PP's `DriverOnly` setting still applies: `"true"` lets only the pilot use 3rd person (passengers locked to 1st); set `"false"` to allow everyone

    This is a one-time setting on the 3PP mod's side — nothing needs changing in CZ Autoz. The 3rd-person view you get is the mod's own smoothed helicopter chase camera.
  </Accordion>

  <Accordion title="Client crashes when spawning a helicopter via an admin tool (VPP, COT, etc.)">
    First confirm **every client and the server are running the exact same mod version** — both the Scripts and the Models/Data PBOs. A version mismatch (for example a client still on an older build while the server runs the current one) is the most common cause of a client crash on spawn, because the helicopter's class and config definitions differ between the two. Fully update / re-subscribe the mod on every client and the server, then retry.
  </Accordion>
</AccordionGroup>

***

## Logging & Diagnostics

CZ Autoz Helicopter generates its own dedicated log files — separate from the standard DayZ `.RPT`. **These are your first stop for any issue.** They are written to your server's profile directory and contain specific, readable diagnostics that the generic RPT cannot provide.

### Log File Overview

| File                                             | Written                                 | Purpose                                                                          |
| ------------------------------------------------ | --------------------------------------- | -------------------------------------------------------------------------------- |
| `$profile:\CZAutoz_Heli_whitelist_status.log`    | Every server start (overwritten)        | Human-readable whitelist result — status, detected IP/port, exact failure reason |
| `$profile:\CZAutoz_Heli_whitelist_debug.log`     | Every whitelist check (appended)        | Low-level API call details, retry attempts, connection errors                    |
| `$profile:\CZAutoz_Heli_debug.log`               | While `logging.CZAutoz_logDebug = 1`    | Verbose mod diagnostics — physics, repair checks, config loading                 |
| `$profile:\CZAutoz_Heli_Activity_YYYY-MM-DD.log` | While `logging.CZAutoz_logActivity = 1` | Timestamped player activity — who flew which helicopter and when                 |

***

### Whitelist Status Log

```
$profile:\CZAutoz_Heli_whitelist_status.log
```

**Check this first whenever helicopters are not responding or controls are dead.** The mod writes this file on every server start. Open it and look for the STATUS line:

| Status                     | Meaning                                 |
| -------------------------- | --------------------------------------- |
| `STATUS : WHITELISTED`     | IP verified — mod is fully active       |
| `STATUS : NOT WHITELISTED` | IP check failed — features are disabled |

The file also shows the **server IP and port the mod detected** — compare these against what you submitted to the whitelist bot. If they don't match, that is your problem. If the status is `NOT WHITELISTED`, the file contains the exact reason and what to do about it.

<Tip>
  This file is overwritten on every server start — it always shows the result of the most recent check.
</Tip>

***

### Whitelist Debug Log

```
$profile:\CZAutoz_Heli_whitelist_debug.log
```

Check this if the status log shows an unexpected result, or if the mod reports it couldn't reach the whitelist API. This file contains the raw API responses, retry attempts, HTTP status codes, and connection error details. Useful for diagnosing firewall blocks or network issues between your server and the whitelist service.

Unlike the status log, this file is **appended** — it accumulates across server starts. Each entry is timestamped so you can identify the relevant session.

<Tip>
  Before digging into the debug log, check whether the CZ Autoz whitelist service itself is online: [status.czautoz.co.uk](https://status.czautoz.co.uk). If the service is down, an API unreachable result is expected and no server-side fix is needed — wait for service restoration and restart.
</Tip>

***

### Mod Debug Log

```
$profile:\CZAutoz_Heli_debug.log
```

<Warning>
  **Do not enable debug logging unless you have been specifically asked to by a CZ Autoz developer.** It is not a general troubleshooting tool — it generates very large log files and can impact server performance on a live server. Only enable it when a developer requests it to investigate a specific reported issue.
</Warning>

For developer-assisted diagnostics only. This log is **only written when debug logging is enabled** — it is off by default and should stay that way.

To enable when asked by a developer:

1. Open `$profile:\CZAutoz_Heli\mod_config.json`
2. In the `logging` section, set `"CZAutoz_logDebug": 1`
3. Restart the server
4. Reproduce the issue
5. Open `$profile:\CZAutoz_Heli_debug.log` and share the contents with the developer

Always set `logging.CZAutoz_logDebug` back to `0` immediately after. Never leave it enabled on a live server.

***

### Activity Log

```
$profile:\CZAutoz_Heli_Activity_YYYY-MM-DD.log
```

A daily timestamped record of every significant player helicopter event — engine starts/stops, seat enter/exit, repairs, refuels, cargo changes, crashes, rotor kills, combat logging indicators, and more. Each entry includes the player's display name, Steam GUID, and helicopter classname.

This is the primary tool for admin investigations, compensation decisions, and dispute resolution. Enabled by setting `logging.CZAutoz_logActivity = 1` in `mod_config.json` — we recommend enabling it on all servers.

See [Global Settings](/server-config/global-settings#logging) for the full list of recorded events and what data each one captures.

***

## Still Need Help?

If your issue isn't covered here, visit the CZ Autoz Discord for community support.

<Card title="CZ Autoz Discord" icon="discord" href="https://discord.gg/7qWZzPUuTq">
  Get help from the community and the development team
</Card>