mpv Conditional Profile Error: How to Fix It

An mpv conditional profile error usually means that a profile-cond expression cannot be parsed, refers to an unavailable property, compares incompatible values, or is quoted incorrectly. The result may be a visible Lua error, a profile that never activates, or configuration loading that appears to stop unexpectedly. The safest response is to reproduce the problem with a clean command, inspect the exact profile, and simplify its condition before changing unrelated subtitle, HDR, hardware-decoding, or output settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

First, determine whether mpv itself can open the same media without loading your normal configuration. Run mpv from a terminal so that warnings and errors remain visible.

On Windows PowerShell or Command Prompt, Linux, or macOS, begin with:

mpv --no-config "path-to-your-file"

Replace the example path with a local media file that you are allowed to access. Keep quotes around paths containing spaces. For a URL, quote the complete URL so the shell does not interpret characters such as &, ?, or ;.

If playback works with --no-config, the player, basic output path, and media are probably usable. The likely cause is now narrowed to mpv.conf, a profile included from another file, a user script, or an option loaded by your regular configuration. Stop investigating codecs or reinstalling mpv at this stage because the clean test has already shown that the failure is configuration-dependent.

If the clean command also fails, read the terminal output carefully. A decoder failure, inaccessible file, unsupported URL, missing external downloader, or unavailable video output is a different problem from a conditional profile expression. Fix that lower-level issue before returning to the profile.

1.1 Find the active configuration location

Make sure you are editing the configuration mpv actually uses. Depending on the operating system and installation method, user configuration commonly resides in an mpv-specific configuration directory. Portable Windows builds can also use a portable configuration directory near the executable. Launching mpv with a custom --config-dir changes the location again.

The terminal log normally reports configuration files as they are loaded. If your edit produces no change, confirm the loaded path instead of creating duplicate configuration files in several locations.

1.2 Distinguish a condition error from a nonmatching condition

A malformed condition usually produces an error about evaluating or parsing the expression. A valid condition that evaluates to false does not produce an error; the profile simply remains inactive. This distinction matters. If the expression is valid but does not match, inspect property names and runtime values. If it cannot be parsed, fix Lua syntax and quoting first.

2. Check the Profile Condition and Its Direct Dependencies

Conditional profiles use Lua expressions. The expression assigned to profile-cond must therefore follow Lua rules rather than shell syntax, JSON syntax, or an invented mpv-specific comparison language.

2.1 Validate Lua expression syntax

A conditional profile has a named section followed by its options. A simple structure looks like this:

[large-video]
profile-cond=p.width ~= nil and p.width >= 3840
hwdec=auto-safe

Lua uses == for equality and ~= for inequality. It uses the words and, or, and not. Operators copied from other languages, including a single =, !=, &&, or ||, will not work as intended.

Check balanced parentheses and string quotes. Smart quotes copied from a formatted webpage or document are not substitutes for ordinary ASCII quotation marks. Keep the condition on one line while troubleshooting so that accidental line breaks cannot obscure the error.

Success means the terminal no longer reports a profile condition parsing or evaluation error. If the intended profile then activates and playback behaves correctly, stop changing settings.

2.2 Use the p property table correctly

Inside a conditional profile expression, mpv properties are accessed through the p table. A straightforward property can be written as p.width or p.duration. Properties whose names contain hyphens or other characters unsuitable for dot notation should use bracket notation, such as p["video-format"].

Do not assume that an mpv option name is also an available runtime property. Options control behavior, while properties report or modify player state. Consult the property list in the official manual when uncertain.

A safe string comparison can look like this:

profile-cond=p["video-format"] ~= nil and p["video-format"] == "hevc"

The exact reported value depends on the property and file. Inspect it rather than guessing. Success means the expression evaluates without errors and matches only media reporting the value you tested.

2.3 Guard against unavailable properties

Many properties are unavailable before a file is loaded, before tracks are selected, or when the current media lacks the relevant information. For example, width is not useful for an audio-only file, and some metadata may not exist for a live stream.

Guard the comparison before applying numeric or string operations:

profile-cond=p.width ~= nil and p.height ~= nil and p.width >= 3840

This short-circuit check prevents Lua from trying to compare nil with a number. Similar guards are useful for duration, codec, container, HDR-related metadata, playlist state, and selected-track properties.

Do not replace every missing value with an arbitrary assumption. Decide whether an unavailable property should make the condition false. Success means audio-only files, partially loaded streams, and ordinary videos no longer trigger evaluation errors.

2.4 Quote strings at the correct layer

There may be three separate parsers involved: your shell, mpv's option parser, and Lua. A condition written directly in mpv.conf does not require shell escaping, but a condition passed on the command line does.

To avoid shell-specific quoting problems, test complex conditions in a small temporary configuration file rather than forcing nested quotes into a one-line command. If command-line testing is necessary, remember that PowerShell, Command Prompt, Bash, and Zsh do not use identical quoting rules.

Within Lua, string values require matching quotes. Do not compare a property to an unquoted word because Lua may interpret that word as a variable. Success means the same expression behaves consistently when placed in the configuration file and no shell error appears before mpv starts.

2.5 Inspect every option inside the profile

A valid condition can activate a profile containing an invalid or unavailable option. Temporarily comment out the profile's options, confirm that its condition evaluates cleanly, and then restore options one at a time.

• For subtitles, verify subtitle file paths, encoding choices, font settings, and selected subtitle tracks.
• For audio and video, confirm that requested track IDs exist instead of hard-coding IDs from another file.
• For hardware decoding, start with a conservative supported mode such as auto-safe rather than forcing one API.
• For HDR or shaders, verify that the selected video output and GPU context support the requested path.
• For screenshots, verify the destination directory, filename template, and write permission.
• For online video, check that the configured yt-dlp executable path is valid and trusted.

Success means adding a specific option recreates the failure. At that point, troubleshoot that option rather than continuing to rewrite the condition.

3. Check Operating System and Media Dependencies

Only investigate system dependencies when the clean test or the activated profile points to them. An expression error itself is not fixed by updating a GPU driver, but a valid HDR or hardware-decoding profile may expose an unsupported output path.

3.1 Verify paths, permissions, and external tools

Confirm that mpv can read included configuration files, scripts, shaders, subtitle files, and media paths. Confirm that it can write to screenshot, cache, watch-later, and log destinations. Test with a simple local path before using a network share or removable drive.

If a profile sets an external downloader path, run that executable directly in the same terminal. Use an official package source or a trusted operating-system package manager. Do not download random binaries or codec packs to solve a configuration expression error.

3.2 Separate stream and file limitations

A local file can expose width, duration, tracks, and metadata quickly. A live stream may reveal properties later, omit duration, change tracks, or fail because of authentication and network restrictions. Test the condition against one known-good local file before concluding that its behavior on a stream is a profile bug.

For playlists, remember that properties can change between entries. A condition should tolerate missing data during transitions. Success means the profile behaves correctly across at least one matching file, one nonmatching file, and any audio-only or stream case you regularly use.

3.3 Check output backends only when the profile activates

If the error appears only after an HDR, shader, or hardware-decoding profile activates, test without the profile's vo, gpu-api, gpu-context, or hwdec override. Let mpv choose defaults first.

On Linux, Wayland and X11 sessions can expose different output paths. Audio backends can also differ by system. On Windows and macOS, driver and platform APIs impose their own constraints. Success means playback resumes with automatic defaults, proving that the profile condition is valid but one activated output option is incompatible.

4. Use mpv Diagnostics to Identify the Exact Failure

Terminal output is more useful than repeatedly editing unrelated settings. Increase logging only enough to expose the relevant profile and property messages.

4.1 Create a persistent log file

Run a controlled test with a log destination:

mpv --log-file=mpv-debug.log "path-to-your-file"

Add a more detailed message level when normal output does not reveal the source:

mpv --msg-level=all=verbose --log-file=mpv-debug.log "path-to-your-file"

Reproduce the issue once, close mpv, and search the log for profile, profile-cond, error, the profile name, and the affected option. Logs may contain local paths, URLs, and filenames, so remove sensitive information before sharing them.

Success means the log identifies the expression, profile, file, or option involved. Stop increasing verbosity once you have a specific error because larger logs can hide the useful line in noise.

4.2 Inspect a named profile

Use --show-profile=PROFILE_NAME to display the options contained in a named profile. Replace PROFILE_NAME with the exact section name. This helps detect an unexpected inherited option, misspelled profile, or profile loaded from a different configuration file.

Showing a profile does not prove that every runtime-dependent option will work. It confirms what mpv believes the profile contains. Success means the displayed options match the file you intended to edit.

4.3 Inspect tracks and runtime state

The stats overlay can help you inspect active decoding and playback information. The track list in mpv's interface or terminal output can confirm available audio, video, and subtitle tracks. These checks are useful when a condition or activated option assumes a particular track exists.

A profile that forces aid, sid, or another track selection can fail to produce the expected result when identifiers vary between files. Prefer automatic or language-based selection where appropriate, and reserve fixed IDs for controlled media sets.

5. Run a Clean Temporary Test Before Making Broad Changes

Create a temporary configuration containing only one profile, one guarded condition, and one harmless option. Point mpv to that temporary setup using an appropriate temporary configuration directory, or back up and temporarily comment out only the suspect section in your existing file. Do not delete the entire configuration folder.

Use this sequence:

1. Confirm the media opens with --no-config.
2. Load the minimal profile with a condition that checks property availability.
3. Verify one matching and one nonmatching file.
4. Add the intended profile options one at a time.
5. Restore scripts, includes, input bindings, and shaders individually.

Scripts deserve separate attention because they can change properties, issue commands, or fail during startup. Temporarily disabling only the relevant script is safer than removing all customization. Input bindings normally do not define conditional profiles, but a binding can invoke a profile, script message, screenshot command, or property change that makes the problem appear interactive.

5.1 Build a safe fallback profile

Keep a simple profile without profile-cond for recovery and manual testing:

[safe-playback]
hwdec=auto-safe
vo=gpu

Adapt the options to those supported by your installation. Invoke the profile manually when needed rather than attaching another complicated condition. A fallback should avoid custom shaders, forced tracks, unusual output APIs, and external dependencies.

Success means the fallback plays ordinary local media reliably. Once that baseline works, keep it unchanged while repairing more specialized HDR, subtitle, streaming, or high-bitrate profiles.

6. Quick Fix Checklist

• Run the same media with mpv --no-config.
• Confirm that mpv loads the configuration file you are editing.
• Replace =, !=, &&, and || with valid Lua operators.
• Access runtime properties through p, using bracket notation for hyphenated names.
• Check for nil before numeric comparisons or string operations.
• Use ordinary matching quotes around Lua strings.
• Test complex expressions in a temporary configuration to avoid shell quoting problems.
• Use --show-profile to inspect the named profile's options.
• Capture one reproduction with --log-file and an appropriate --msg-level.
• Restore profile options, scripts, and includes one at a time.
• Use automatic output and hardware-decoding defaults to isolate backend problems.
• Stop changing settings as soon as the error disappears and the correct profile behavior is verified.

7. Frequently Asked Questions

7.1 Why does profile-cond report a Lua error?

The usual causes are invalid Lua operators, unmatched quotes or parentheses, an unquoted string, or an operation involving an unavailable property. Simplify the expression and add a nil guard before comparing values.

7.2 Why does a valid conditional profile never activate?

The property may have a different name or value than expected, or it may not be available at the evaluation point. Inspect runtime output and test a known matching file. A false result without an error means the expression is valid but its criteria were not met.

7.3 Can I use p.property for every mpv setting?

No. The p table exposes mpv properties, not every option. Use bracket notation for property names that cannot be represented safely with dot notation, and verify the property in the official manual.

7.4 Why does the condition work in mpv.conf but fail in my terminal?

Your shell parses the command before mpv and Lua see it. Quotes, dollar signs, ampersands, parentheses, and other characters may be altered. Put the expression in a temporary configuration file or apply the quoting rules for your specific shell.

7.5 Should I reinstall mpv or delete my configuration?

Not initially. If --no-config works, reinstalling is unlikely to repair a malformed condition. Preserve your configuration, isolate the suspect profile, and test a temporary minimal setup. Consider reinstalling only when a trusted package is damaged or the clean command also fails for a confirmed installation reason.

7.6 When is the mpv conditional profile error fixed?

The issue is fixed when the log contains no condition evaluation error, matching media activates the intended profile, nonmatching media remains unaffected, and fallback playback still works. Once those checks pass, stop editing unrelated audio, subtitle, video, and output settings.