mpv Lua Script Error: How to Fix It

An mpv Lua script error usually means a user script failed to load, encountered invalid Lua syntax, called an unsupported mpv API function, could not find a dependency, or received a value it did not expect. The visible symptom may be a traceback in the terminal, a broken key binding, a missing menu, subtitles that no longer update, or an mpv player issue that appears only with your normal configuration. The safest approach is to reproduce the failure with one script and one known-good media file, read the first meaningful error in the log, and change only the component implicated by that error.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin by separating the Lua failure from your regular mpv configuration. A normal setup can automatically load scripts, profiles, shaders, input bindings, and platform-specific options. Any of these can obscure the original problem.

First, confirm that the media itself opens without your configuration:

mpv --no-config "path/to/test-video.mkv"

On Windows, run this from Command Prompt or PowerShell after replacing the path with a real local file. On Linux or macOS, run it from a terminal. Keep quotation marks around paths containing spaces.

If the file plays correctly, mpv's core playback path is working. Stop changing video, audio, HDR, or hardware-decoding settings for now. The fault is likely in the disabled configuration, an automatically loaded script, or an interaction between them.

Next, load only the suspected script:

mpv --no-config --script="path/to/script.lua" "path/to/test-video.mkv"

Success means the video opens and the script's expected command, menu, display, or key-driven behavior works without an error. If that happens, the script probably conflicts with another script or depends on an option in your normal configuration. If the same error appears, you have isolated the failure to the script, its dependencies, its data, or its compatibility with your mpv build.

1.1 Use a Simple Local File First

Use a short local video that mpv normally plays. Do not begin with an online URL, network share, HDR title, unusual subtitle format, or high-bitrate stream. Those inputs add unrelated failure points such as yt-dlp, authentication, network access, GPU output, and demuxer behavior.

If the script only handles a specific feature, you may need a representative file. For example, a subtitle script requires a file with an appropriate subtitle track or a separately loaded subtitle file. Establish ordinary playback first, then introduce the required feature.

1.2 Verify That the Error Actually Comes From Lua

Look for a script name, a .lua path, a line number, or words such as stack traceback, attempt to call, nil value, module not found, or syntax error. An error from the video output, audio device, demuxer, or network layer is not automatically a Lua error merely because a script was active.

If no Lua filename or script message appears, test the underlying playback problem independently. This prevents an unrelated mpv not working symptom from sending you into unnecessary script edits.

2. Check the Setting Directly Related to the Script Failure

Once the clean test identifies the script, inspect the exact option, command, or property named near the beginning of the error. Lua tracebacks are read most effectively from the first concrete failure outward, rather than from the final repeated stack entries.

2.1 Read the First Useful Traceback Line

A traceback often contains several frames. Find the earliest line that names the user script and describes the failure. Common patterns include:

• unexpected symbol or expected ... near, which indicates invalid Lua syntax
• attempt to call a nil value, which can indicate a missing function or incompatible API assumption
• attempt to index a nil value, which often means a property, table, track, or returned object was absent
• module 'name' not found, which indicates a Lua dependency or module search-path problem
• error loading script, followed by a path and line number

Open the referenced file in a plain-text editor and inspect the stated line plus nearby lines. A missing quote, comma, parenthesis, or end may cause the parser to report the error slightly after the actual mistake. If you did not write or modify the script, compare it with the trusted upstream copy rather than guessing at syntax repairs.

Success means mpv loads the script without printing the same traceback. Once the original error disappears and the feature works, stop editing. Warnings unrelated to the script can be investigated separately.

2.2 Verify mpv API Assumptions

mpv scripts commonly use functions such as mp.get_property, mp.get_property_native, mp.set_property, mp.command, mp.command_native, event observers, timers, and key bindings. A script can fail if it assumes a function, command, event, or property that is unavailable or behaves differently in the installed mpv build.

Check the script's documentation for stated mpv requirements. Then compare the calls in the failing line with the current mpv manual and Lua scripting documentation. Do not replace function names merely because a forum comment recommends it. Confirm the expected arguments, return type, and treatment of unavailable properties.

Property values also matter. A script may assume that a track ID, filename, duration, video parameter, or subtitle property always exists. During startup or with an audio-only file, that value may legitimately be unavailable. Script authors should handle nil and unavailable properties instead of treating them as guaranteed values.

2.3 Check Script Dependencies

Some scripts are self-contained, while others require companion Lua files, JSON data, executables, fonts, directories, or configuration files. Read the script's installation instructions and verify each required item. Preserve the expected directory layout and filename capitalization, especially on case-sensitive Linux filesystems.

If the script invokes an external program, confirm that the program is installed from a trusted source and can be found in the environment used to launch mpv. A tool available in your interactive terminal may not be visible when mpv is launched from a desktop shortcut or file manager.

For yt-dlp-related scripts, distinguish between an mpv Lua failure and an external-tool failure. Run mpv from a terminal and inspect whether the message names the script, yt-dlp, a network extractor, or the remote site. Do not download replacement binaries from random mirrors.

2.4 Validate Config Option Names and Script Options

A script may read its settings from a script-specific options file. A misspelled key, obsolete option, malformed number, or invalid path can produce unexpected values. Check the script's documentation for the correct options filename and accepted keys.

Also inspect mpv.conf, profiles, and command-line arguments for options used by the script. Do not assume an option name is valid because it resembles an mpv property. Command-line options, properties, and input commands are related but not interchangeable in every context.

Temporarily remove or comment out only the suspicious line, then repeat the isolated command. If the script works, restore the line with the documented name and value. That successful retest is your stopping point.

3. Rule Out Conflicting Scripts, Bindings, and Profiles

Two valid scripts can still conflict. They may register the same key, observe and rewrite the same property, create identically named script messages, or alter tracks and playback state in incompatible ways.

3.1 Add Other Scripts Back One at a Time

After the suspected script works with --no-config --script, create a temporary test that adds one additional script at a time using another --script argument. Keep the media file and all other conditions unchanged.

1. Test the target script alone.
2. Add the script most likely to control the same feature.
3. Repeat until the error returns.
4. Remove the last-added script and confirm that the error disappears again.

This A-B-A confirmation is stronger than assuming that the last visible message identifies the conflict. Once you know the pair involved, check both projects' documentation for settings that disable overlapping behavior.

3.2 Inspect input.conf and Script Bindings

If the script loads but a key does nothing, the problem may be a binding rather than a runtime failure. Inspect input.conf for duplicate keys, misspelled script-message commands, incorrect quoting, or a command intended for a different script name.

Use the exact script-message syntax documented by the script. Remember that keyboard shortcuts can also be captured by the window manager, desktop environment, or operating system. Success means the intended script action runs consistently and the terminal does not show an unknown command or script-message error.

3.3 Check Profiles With show-profile

A profile can silently activate options that change hardware decoding, tracks, shaders, video output, audio output, or script behavior. Ask mpv to display the profile's contents:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the actual profile name. Review the expanded options and compare them with the feature the script controls. Test without activating the profile, then add its options individually if necessary.

If the error only occurs with the profile, do not rewrite the Lua script first. Isolate the profile option responsible and verify its spelling and supported values in the mpv manual.

4. Check Operating System and External Causes When Relevant

Operating system checks are useful only when the traceback or script purpose points toward files, programs, devices, or network resources. A pure syntax error will not be fixed by changing GPU drivers or permissions.

4.1 File Paths, Permissions, and Shell Quoting

If the error mentions opening, reading, writing, or executing a path, confirm that the path exists and that your user account can access it. This commonly affects subtitle exports, thumbnails, history files, screenshots, playlists, named pipes, and IPC sockets.

Quote paths containing spaces. Be careful when moving commands between PowerShell, Command Prompt, Bash, and Zsh because their escaping rules differ. For diagnosis, use a short absolute path with ordinary characters. If that works, the original path or shell quoting is the likely cause.

Do not run mpv as an administrator or root merely to bypass an unclear error. Correct ownership and permissions on the specific file or output directory instead.

4.2 Video Output, Hardware Decoding, HDR, and Display Servers

A Lua script that reads video parameters, toggles HDR behavior, manages shaders, or changes hardware decoding may expose a graphics problem. Test the same file without the script. If playback itself fails, investigate the video output, GPU driver, hardware decoder, and display environment before debugging Lua.

On Linux, note whether the session uses X11 or Wayland. On all platforms, compare software decoding with your normal hardware-decoding configuration only when the log points to decoder or GPU initialization. If clean playback works and the isolated script still throws the same Lua traceback, return to the script rather than cycling through graphics options.

4.3 Audio, Subtitle, and Track Assumptions

Scripts that select tracks may fail when a file has no video, no subtitles, multiple editions, external tracks, or metadata different from what the author expected. Inspect the available tracks in mpv's on-screen interface or terminal output. Test with a file whose tracks are known.

A robust script should tolerate missing tracks. If the failure occurs only when subtitles are absent, for example, the script likely needs a guard for an unavailable subtitle property. Changing the audio backend will not fix that condition.

4.4 Network Streams and External Tools

For an online URL, first confirm that mpv can open the URL with --no-config. If it cannot, the problem may involve network access, certificates, authentication, yt-dlp, the remote service, or an unsupported stream rather than Lua.

If the URL opens cleanly but fails when the script is added, capture the script traceback. Check whether it assumes a local filename, seekable media, known duration, or writable cache. Live and network streams may not provide those characteristics.

5. Use mpv Logs to Identify the Exact Failure

Terminal output is usually the fastest diagnostic tool. Launch mpv from a terminal rather than by double-clicking a media file, reproduce the error once, and preserve the complete output.

5.1 Increase Message Detail

Use a verbose message level with the isolated script:

mpv --no-config --msg-level=all=v --script="path/to/script.lua" "path/to/test-video.mkv"

Verbose output can be extensive. Search for the script filename, lua, error, traceback, and the name of any external dependency. Read several lines before and after the failure because initialization messages often reveal the bad value or missing resource.

5.2 Save a Log File

To avoid losing terminal output, write it to a file:

mpv --no-config --msg-level=all=v --log-file="mpv-debug.log" --script="path/to/script.lua" "path/to/test-video.mkv"

Reproduce the problem, close mpv normally, and inspect the log. Before sharing it publicly, remove private URLs, usernames, local paths, tokens, cookies, and other sensitive information. A useful bug report includes the relevant traceback, the isolated command, the script source or version, the operating system, and mpv's reported version.

5.3 Use the Stats Overlay and Track Information Carefully

The stats overlay can confirm decoder, frame, timing, and rendering behavior when a script interacts with playback performance. Track information can confirm whether the audio, video, or subtitle track expected by the script actually exists. These tools provide context, but they do not replace the Lua traceback.

If stats show stable playback and the only failure is a Lua exception, avoid unrelated tuning of cache, hardware decoding, or video output. The script remains the primary target.

6. Run a Clean Temporary Test Before Making Permanent Changes

Do not delete the entire mpv configuration folder. Instead, use temporary commands and make a backup of only the file you intend to edit. This preserves working profiles, shaders, bindings, and script settings.

A reliable test sequence is:

1. Run the media with --no-config.
2. Run it with --no-config and only the target script.
3. Add the script's required options or dependency.
4. Add the relevant profile or binding.
5. Add other scripts one at a time.
6. Repeat the exact action that originally caused the failure.

Change one variable per run. Keep the same media file, launch method, and script action. If a change fixes the error, repeat the previous failing command once and the corrected command once. This confirms causation and avoids accidental fixes caused by a different file or environment.

Success is not merely the absence of a visible popup. The script should load without a traceback, its intended action should work, playback should remain stable, and the terminal should not report repeated script failures. At that point, stop changing settings.

7. Quick Fix Checklist

• Open a known-good local file with mpv --no-config.
• Load only the failing script with --no-config --script.
• Read the first useful script filename, line number, and error message.
• Check the failing Lua line and nearby syntax.
• Verify the script's documented mpv requirements and API calls.
• Install only documented dependencies from trusted sources.
• Check script-options files for obsolete keys, invalid values, and bad paths.
• Add other scripts back individually to find conflicts.
• Inspect duplicate or malformed commands in input.conf.
• Use --show-profile to review relevant profile options.
• Use verbose terminal output and --log-file for a complete traceback.
• Investigate permissions, GPU, audio, network, or yt-dlp only when the evidence points there.
• Stop once the isolated failure is gone and the script feature works normally.

8. Frequently Asked Questions

8.1 What does an mpv Lua script error mean?

It means a Lua user script could not be parsed, initialized, or executed successfully. Typical causes include syntax mistakes, missing dependencies, unsupported API assumptions, invalid script options, unavailable media properties, and conflicts with other scripts. The traceback usually identifies the script and approximate source line.

8.2 How do I test one mpv script without loading my configuration?

Run mpv --no-config --script="path/to/script.lua" "path/to/file". This avoids the normal configuration and automatically loaded user scripts while explicitly loading the target script. If it works, add the relevant configuration components back one at a time.

8.3 Why does the script work alone but fail in my normal setup?

The likely cause is a conflicting script, duplicate input binding, profile option, script-options value, shader, or playback setting. Add these components back individually until the error returns, then confirm the result by removing the last-added component.

8.4 Can updating mpv fix a Lua script error?

It can help when the script explicitly requires an API, command, or property unavailable in your build. However, updating will not repair invalid Lua syntax, missing files, incorrect paths, or unsupported assumptions inside the script. Check documented requirements and the traceback before changing software.

8.5 Why does the error happen only with subtitles or online streams?

The script may assume that a subtitle track, local filename, duration, seekable timeline, or writable destination always exists. Online and live streams frequently provide different properties from local files. Test the same script with and without the relevant track or stream to identify the missing condition.

8.6 What should I include when reporting the problem?

Include the complete sanitized traceback, the smallest command that reproduces it, the script name and source, your operating system, mpv's reported version, and a description of the expected behavior. State whether the problem remains with --no-config --script. Never include private stream credentials, tokens, cookies, or personal paths.