Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Troubleshooting and known limits

Match the manual to the build

Check About before copying configuration from a manual. Its version string matches the manual’s label: the package version at an exact Git tag, or a string such as 1.1.0+g12345678 for an untagged source build. The command copperline --version prints only the package version, so it cannot distinguish source revisions.

The online manual is replaced when a release is published; its banner names the version and source revision it describes. A source snapshot can have changes beyond the release with the same package version. The persistent sidebar footer keeps that identity visible even when the banner has been dismissed.

For an installed release, download the matching Copperline-VERSION-manual.pdf from that version’s GitHub release. For a source build, build the manual from the same checkout as the executable. The changelog records configuration changes and save-state compatibility. Features documented for a later build may be rejected by an older executable.

Configuration will not load

An unknown field error names a key the executable does not accept. Check its spelling, its TOML table, and the manual version. A key belongs to the last uncommented [table] header above it; commenting out a header does not comment out its values. Compare with the copperline.example.toml shipped with the same source revision. Do not copy a newer example wholesale into an older installation.

These older spellings have specific compatibility behaviour:

Older settingCurrent setting or actionCompatibility
[machine] model[machine] profileAlias still accepted. [cpu] model continues to select the CPU.
[audio] filter[audio] audio_filterAlias still accepted.
[floppy.dfN] bridge_speed[floppy.dfN] replay_speedAlias still accepted; use normal or fast (100 or 200 also work).
--floppy-bridge-speed DFN SPEED--floppy-replay-speed DFN SPEEDAlias still accepted.
[lide] drives[lide] drive0 through drive3Old array still accepted; named slots override it.
[floppy.dfN] bridge_auto_cacheRemove the key.Rejected. FluxBridge no longer does a background disk sweep.
[emulation] speedRemove the key.Accepted with a warning and ignored; it does not choose a timing model.
[recording] native_screenshot_buttonRemove the key.Accepted and ignored; native screenshots use Cmd+Option+S / Ctrl+Alt+S and --native-screenshots.

Replace an alias rather than adding the current spelling beside it. Both spellings together are a duplicate-field error. For CPU speed, use [cpu]; for running faster than wall-clock, use the warp settings.

An invalid escape sequence error on Windows often means a path contains backslashes inside TOML double quotes. Use literal single quotes, for example rom = 'C:\Kickstarts\KICK31.ROM', or forward slashes. See Paths on Windows.

If a different machine starts than expected, check which configuration was loaded. The order is explicit --config, ./copperline.toml, a config beside the executable, then the launcher’s saved default. --factory bypasses the last two; it does not bypass --config or ./copperline.toml. See the configuration reference for platform-specific locations and relative media paths.

Isolate a boot, display or audio problem

Run from a folder without a copperline.toml to capture the bundled AROS boot on a known A500 profile:

copperline --factory --model A500 --noaudio \
  --screenshot-after 10 boot.png

This exits after ten emulated seconds and needs no window or audio device. The resulting PNG checks the core’s output independently of host presentation. Then repeat with your explicit --config and media. Keep the failing config and a minimal timed input script when reporting a difference. The headless guide describes scheduled inputs and captures.

A save state will not load

Save states have a container version and separate subsystem chunk versions; these numbers are distinct from the Copperline release version.

State formatCurrent reader behaviour
Flat states from Copperline 0.19 and earlier (container 1-80)Refused; boot the guest again and create a new state.
Chunked container 81Accepted without the later thumbnail/metadata card.
Chunked container 82Current container. Required chunks and their versions still need to be supported by the reader.
Older subsystem chunkUpgraded only when a migration exists. A missing migration fails with the chunk name and versions.
Newer subsystem chunkRefused. Use the build that wrote it or a compatible newer build.

For example, 1.1.0 reads old CIA version-1 chunks by migration and writes CIA version 2. That does not make the resulting states readable by 1.0.x. Forward compatibility is not guaranteed merely because the container version is the same. Preserve a copy before trying a state in another build.

1.2.0 is another one-way boundary even though the container and chunk versions did not change: 1.2.0 reads 1.1.0 states, but 1.1.0 cannot read 1.2.0 states. Its decoder requires the floppy drives’ external_id_mode and the device clock’s wall-clock fields, which newer states no longer write. An error naming one of those missing fields calls for a newer reader or a new snapshot made by the older executable.

Built-in board drivers that run from a ROM inside Copperline are not stored in a state. 1.2.0 changed the copperhf.device driver, so a 1.1.0 state saved with a [copperhf] drive attached can hang after loading in 1.2.0; boot that machine afresh and save a new state.

The reader must also have support for every expansion board in the state. A file that loads in one feature build may fail in another. The format reference describes the checks. copperline-ctl state-info FILE.clstate inspects metadata without launching an emulator; it does not prove every machine chunk can be restored.

A state restores its saved machine, including RAM, ROM and chipset, even when the current config selects something else. It is not a disk backup: hard-drive and CD images reopen by path, and later writes to a host disk or mounted folder are not undone. Keep the original backing images available. Physical drives, host networking and other live services also prevent a full timeline rewind. The host paths and mounts a state names are opened on load whatever the current config says, so only load states from a source you would accept a config file from. See save states and the determinism boundaries.

Known emulation limits

These limits describe hardware behaviour, rather than a compatibility promise for individual programs. The linked subsystem chapters give the details.

Hardware or modeLimit
68020/030/040/060 timingThe later CPUs do not have a complete pipeline/overlap timing model. Instruction correctness and measured bus timing do not imply cycle-exact accelerator execution. CPU timing.
JIT and CPU speed = "fastest"JIT batches execution; fastest also adapts the CPU clock to spare host time. Use the default fixed clock and JIT disabled for precise timing investigations. CPU execution modes.
External 68851 MMU on a 68020Not modelled. The on-chip MMUs on the full 68030/040/060 are separate supported devices; EC variants omit them. CPU configuration.
A2024 / UHRES dual-scan outputNot emulated. Chipset gaps.
External genlockGeneric physical genlock video input/output and ZD key-signal output beyond register storage are not emulated. External genlock sync ([chipset] genlock), the Video Toaster 4000 video-slot card, and the CD32 FMV module’s internal digital video compositing are separate supported features. Chipset gaps.
AGA display fetchSub-unit DDF stop effects beyond whole fetch-unit completion are not modelled. Chipset gaps.
CD+G graphicsSubcode R-W data reaches the CDTV and CD32 only from an image that stored it: a .sub file beside the image, a cue sheet CDG track, or a CHD with raw subcode. CHD “cooked” subcode is not read. CD images.
Toccata recordingThe capture FIFO is a stub: reads return zero and no record half-full interrupt fires. Playback is implemented. Toccata scope.
Video FlyerClip recording into the Flyer, SMPTE time code, and the TBC module are not emulated. Playback, editing/cutting, and clip import/export are supported. Video slot.
SCSI tapeSetmarks, partitions, READ POSITION, LOCATE, and mechanical tape-motion timing are not modelled. Tape drives.

Browser and libretro builds also have host integration limits; see the browser guide and libretro guide for the available features in each frontend.

Reporting a reproducible problem

Include the Copperline version (and source revision for a development build), host OS, selected machine profile, config, exact command and timed inputs, and the first emulated time at which the result differs. Attach a screenshot and the relevant stderr log. A panic also writes copperline-crash.txt; see logging and crash reports. Describe the ROM/media and their checksums without uploading copyrighted images. State whether the problem reproduces with JIT disabled and whether it occurs headlessly, in the window, or both.