Troubleshooting

Start with ripdoctor doctor. It reports missing tools, beets plugins that did not load, a library the two disagree about, a pool it cannot write to, and any threshold moved from its default.

The console at the bottom of the interface holds the raw output from every tool. When something fails, the reason is usually there in full.

Signing in

The password is lost. It is hashed on disk and cannot be read back. Delete ~/.config/ripdoctor/auth.json and start the server again — it generates a new login and prints it once.

Recording

Nothing is recorded, or the file is silent. Run ripdoctor probe. It says whether music, silence or nothing at all arrived. Then ripdoctor devices to confirm the device name, and check the input is selected on the interface itself.

The device does not look like the turntable. The Rip panel warns and offers a record from it anyway tick. The warning is a guess; the tick is there because the guess can be wrong.

It stops in the middle of the record. The auto-stop read a quiet passage as the run-out. When it asks, choose Keep recording and the clock restarts. For a record that is quiet throughout, untick Stop at the run-out before starting, or raise autostop_dwell.

It never stops. The run-out is not reading as quiet enough. Stop it by hand; a 35-minute hard cap applies regardless.

The capture is there but was never encoded. The process was interrupted. Unfinished capture in the Rip panel offers to encode it, or ripdoctor salvage <album> does the same.

The meter and the levels look wrong. Check the rate and depth match what the interface actually sends. A capture metered at the wrong rate measures the wrong frequency band, and every measurement after that is off.

Uploading

The upload stopped part-way. What arrived is kept. Reopen the Upload tab, pick the same file again and press Upload; it continues from where it stopped. You have to choose the file a second time because a browser cannot re-read one across a page reload.

that file has N channels and this is a stereo tool. A surround source. Downmix it to stereo before uploading; a six-channel track in a music library is a worse place to discover this.

that file has no audio in it. ffmpeg found no audio stream — an image, a text file, or a download that did not finish.

the encoded side would not decode. The source was damaged, or the transfer was. Nothing was placed. Try the file again, and play it locally first to check it is intact.

<record> already has side a. That record was already ripped or uploaded. Discard the existing side first, or work on a new record.

The first pass fits badly after an upload. Probably a gapless album — see Uploading a file. The boundaries are still correctable by ear; there is just no silence to snap to.

Finding the release

The search finds nothing. Try the artist and album separately, or a shorter form of either. Some releases are filed under a different artist credit than the sleeve.

that release has no track durations. Nothing to fit boundaries against. Pick a different entry — an entry with durations fits better than a vinyl entry without them, whatever the format.

The tracklist is on the wrong sides. The release has a different track order or a different count from your pressing. Pick the vinyl release you actually own, or fix it by hand.

Boundaries

A boundary is far off and the delta is large. Audition it with A. Tracks that run together with no silence between them have no gap to detect, and the boundary has to be set by ear.

The whole side is off by a few seconds. A different pressing to the release you chose. The boundaries are still correctable by hand, and the deltas will stay large.

A cut lands on the music. Nudge with ←/→ and audition again. Increase lead and tail if every cut is tight in the same way.

Cutting

BadPlan: ... end N is not after start M. Two boundaries crossed. The message names the track. Fix it in the track table and cut again.

Old files are mixed in with the new ones. They are not — cutting clears the review directory first. If the finished-tracks list and the console disagree, believe the file list; it is read back from disk.

Importing

nothing to import - cut the tracks first. The review directory is empty. Cut the tracks.

N of the tracks are still in review - beets did not take them. beets declined. The transcript under details says why. The two common causes are a duplicate it will not overwrite, and stale rows — see below.

beets treats it as a duplicate and stops part-way. Its database still counts files that were deleted outside it. The dialog offers Clear the stale rows, which removes database rows only, never files, and refuses unless every file is confirmed absent.

The record was imported but has no cover art. Check ripdoctor doctor — fetchart and embedart are probably not loaded. Meanwhile the panel after the import will fetch or accept one; see Cover art.

Everything imports but nothing has ReplayGain. Same cause: the replaygain plugin is not loaded, or its backend is missing.

Files land in ~/Music instead of the library. beets has no configuration file, so it is using its own default directory. See Setting up beets.

Everything works from a shell and not as a service. A service does not inherit your shell's environment. Set BEETSDIR in the unit file.

A player cannot read the imported files. Permissions. Set file_mode and dir_mode to something the player's user can read.

Archiving

Archive rip stays disabled. The record is not confirmed in the library yet. Hover the pipeline strip; it says what is missing. RipDoctor asks the importer where it filed the record, so this reflects what beets actually did.

A side will not archive. It did not verify. The console says which. A truncated capture is re-encoded automatically; one that will not decode at all needs re-ripping.

Re-ripping and punching

no saved cut yet - nothing to punch into. Punching fits against a saved cut. Cut and import the record first.

Align from archive is not there. It appears only when the record has a side in raw/ and an archived copy as well — that is, mid-re-rip.

Alignment cannot find the match. Usually a capture that starts inside the music, or a very different take. Fit the side with a first pass instead.

Where things went

Nothing is deleted where it can be avoided:

What	Where it goes
a side replaced by a re-rip	archive/<slug>/_superseded/
a library file replaced by a punch	archive/<album>/_punched/
the punch capture itself	archive/<album>/_punched/
raw sides after archiving	archive/<slug>/, kept indefinitely