Troubleshooting

Start with the symptom you can see or hear. Keep the exact status message: Queued, Missing, Needs review, and an unavailable output describe different problems.

A loaded deck is silent#

Loading leaves a deck stopped. Click a section pad or select one and press Enter in Perform. A quantized launch may show Queued until its boundary arrives.

If the playhead is moving, check these controls:

1. Deck mute and volume, followed by master volume.
2. Stem selection. Z restores Full on the focused deck.
3. Crossfader position and the deck’s Left / Right / Thru assignment.
4. EQ and filter. Option+V resets the focused deck’s gain trim, EQ, and filter.
5. A held scratch waveform or momentary cut. Release the mouse and keys; Escape releases an active scratch gesture.
6. The selected Master device, stereo pair, and physical speaker controls.

Deck meters are before the fader, so a moving deck meter does not prove that its Master output is turned up. After a device reconnect, Grit leaves decks stopped; launch again when your routes are ready.

I cannot preview a track#

With headphones configured, inspect Cue / Preview, Cue level, and the Cue / Master blend. A blend fully toward Master excludes the preview bus.

Without a cue output, preview uses Master only while all decks are stopped. Queued launches, scratches, and audible effect tails can also block it. Stop the decks and let tails end, or configure a headphone output to audition while performing.

In Library and the Perform browser, use Shift+Enter for preview. In the track editor, Space previews the selected section. Plain Space elsewhere controls the focused deck. See Audio and headphones.

A track will not load, or an output will not change#

Grit protects active decks from replacement. Choose a stopped deck, or stop the intended target before loading. Save or discard any open preparation draft first.

Audio settings also require stopped playback and pending audio work to finish. Read the explanation beside the disabled control. An accepted output change reloads decks stopped.

If a selected interface has disappeared, reconnect it or choose a connected Master device or System Default. This also clears an unavailable separate cue device. Verify both speaker and headphone routes afterward.

The grid drifts or launches feel late#

Open Edit and preview with Metronome. A steady offset usually calls for a first-beat adjustment; increasing drift calls for checking BPM. Test a later section as well as the beginning. ÷2 / ×2 correct half- and double-tempo estimates. Save the result before loading it.

In Perform, inspect the Sections and Juggle grids in the toolbar. On Sections, 1 Bar, 4 Bars, 8 Bars, and End intentionally wait for a boundary; Juggle decides when bar juggles, play, and resume land. Free launches immediately. A resume preserves its paused position and waits for the matching beat phase; it does not restart the section.

For temporary phase correction on a playing deck, hold , / .. This bends playback and does not repair a saved beatgrid. See Preparing tracks for permanent corrections.

Stem or pitch controls are unavailable#

Stem controls depend on the track’s prepared audio. Check the Library’s enhancement state and use Enhance pending or the track’s enhancement action when needed. A Needs review flag is a separate listening decision.

Pitch lock and Key Sync require supported prepared playback. Key Sync also needs a session tempo within 80–125% of the track’s BPM. Hover the control for its reason, then check tempo and preparation rather than repeatedly toggling it.

A source is missing#

Use the track’s Relink action to choose its matching source. Grit checks compatibility and preserves the track’s edits and set references. Do not substitute an unrelated song just to remove the warning.

Reconnect external storage and use Rescan files & artwork when availability has changed. Back up the complete ~/Music/Grit folder; the catalog alone does not contain all managed audio. See Library and import.

A controller knob seems unresponsive#

Absolute MIDI knobs and faders use pickup. Move the hardware control through the current on-screen value before expecting it to take over. A mouse change or set recall can require pickup again.

For an APC40 MK1, enable its preset in Settings → Controls and release the controller from other applications. If you selected that APC40 as a generic MIDI Learn input, its learned assignments replace its preset; choose None · APC40 preset only to restore the preset. See MIDI controllers.

Saving fails or quitting waits#

An unsuccessful preparation save keeps the draft editable. Resolve the reported storage problem and retry. Save or discard the editor draft before quitting; Grit waits for pending durable writes. Escape can cancel a pending shutdown.

If startup reports that another Grit process owns the library, close that instance before trying again. If Grit offers recovery for a damaged catalog, read the restore confirmation carefully and keep your library backup.

Report a reproducible problem#

Include the Grit build version, macOS version, audio interface and output pairs, controller, exact action, and displayed message. For audio problems, add source BPM, session BPM, both launch grids, pitch-lock state, and whether Cue is affected too. A short recording and the smallest repeatable sequence help distinguish timing, routing, and source problems.