mpv IPC Server Not Working: How to Fix It

When the mpv IPC server is not working, the usual symptom is straightforward: mpv can play media, but a JSON IPC client cannot connect, receives a connection error, or connects without returning a response. The most likely causes are an incorrect --input-ipc-server value, Windows named pipe syntax, Unix socket permissions, startup timing, shell quoting, a configuration override, or sandbox isolation. Less commonly, mpv exits before creating the endpoint because another playback, script, driver, or media-related error stops startup. The safest approach is to prove IPC works with a clean command, query one simple property, and then reintroduce your normal configuration gradually.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start by separating an IPC connection failure from a broader mpv player issue. Do not begin by changing subtitles, shaders, hardware decoding, or scripts. First launch a clean mpv process that is expected to remain open and create an IPC endpoint.

1.1 Test on Linux or macOS

Open a terminal and run:

mpv --no-config --idle=yes --input-ipc-server=/tmp/mpv-test-socket

The --no-config option prevents your normal configuration and user scripts from affecting the test. The --idle=yes option keeps mpv running without requiring a media file. The final option asks mpv to create a Unix domain socket at the specified path.

In a second terminal, confirm that the socket exists:

ls -l /tmp/mpv-test-socket

Success means the path exists as a socket while mpv remains running. If the path does not appear, inspect the first terminal for an option parsing, permission, or startup error. Do not continue changing client settings until mpv creates the socket.

If socat is already installed from your operating system's trusted package repository, send a basic JSON request:

printf '{"command":["get_property","mpv-version"]}\n' | socat - UNIX-CONNECT:/tmp/mpv-test-socket

A successful response is a JSON object containing "error":"success" and a data value. That proves mpv created the server, the client reached it, and JSON commands work. Stop changing mpv settings at this point if your real client can be corrected to use the same endpoint.

1.2 Test on Windows

Windows uses a named pipe rather than a filesystem socket. In Command Prompt, launch mpv with:

mpv.exe --no-config --idle=yes --input-ipc-server=\\.\pipe\mpv-test

The full named pipe path is \\.\pipe\mpv-test. A client may ask for the complete path or only the pipe name, mpv-test. Check that client's documentation instead of assuming both formats are accepted.

Keep the mpv process running while testing. Unlike a Unix socket, a Windows named pipe is not a normal file that can be found in File Explorer. Success is demonstrated when a client opens the pipe and receives a valid JSON response.

1.3 Use a Simple Property Query

Send one newline-terminated JSON command after connecting:

{"command":["get_property","mpv-version"]}

JSON IPC messages must be valid JSON, and commands are separated by newline characters. A client that opens the endpoint but never appends a newline may wait indefinitely. Start with mpv-version because it does not depend on a loaded file, selected track, subtitle state, or playback position.

If this query works, the IPC server itself is functioning. Troubleshoot the client's command construction or event-handling logic rather than modifying mpv playback settings.

2. Check the IPC Option and Configuration Directly

The IPC server is enabled by the input-ipc-server option. The effective value must identify the same socket or pipe that the client attempts to open.

2.1 Verify the Exact Option Name

Use two leading hyphens on the command line:

--input-ipc-server=/path/to/socket

In mpv.conf, omit the leading hyphens:

input-ipc-server=/path/to/socket

A common mistake is copying command-line syntax directly into a configuration file or using an old path in one location. Search your configuration, launch shortcut, wrapper script, service file, and client settings for every occurrence of input-ipc-server.

2.2 Check Which Configuration Is Actually Loaded

mpv can receive options from command-line arguments, platform-specific configuration directories, profiles, wrapper programs, and scripts. A command-line value normally takes precedence over the general configuration, but a launcher may invoke a different mpv binary or use a different configuration directory than expected.

Compare these two launches:

mpv --idle=yes --input-ipc-server=/tmp/mpv-normal-socket
mpv --no-config --idle=yes --input-ipc-server=/tmp/mpv-clean-socket

If only the clean command works, your regular configuration or startup environment is involved. Re-enable configuration components gradually rather than deleting the entire config folder.

2.3 Inspect Profiles and Input Bindings

A profile can change options when a file, protocol, display mode, or user-defined condition is selected. Use --show-profile=PROFILE_NAME to print the contents of a known profile:

mpv --show-profile=gpu-hq

Replace gpu-hq with the profile you actually use. Look for options that cause startup failure or unexpectedly alter your launch path. Input bindings usually do not prevent socket creation, but a binding that immediately runs quit, invokes a failing script command, or starts another process can make the server appear unreliable.

Success means mpv remains open and retains the expected IPC endpoint after the applicable profile and bindings load.

2.4 Treat Playback Options as Secondary

Subtitle settings, audio and video track selection, output drivers, HDR options, shaders, screenshot templates, hardware decoding, and yt-dlp settings do not normally control JSON IPC. Do not change them merely because a client cannot connect.

They become relevant only when mpv exits, hangs, or crashes before or shortly after creating the endpoint. For example:

• A malformed shader path may produce an error during video initialization.
• An unavailable audio or video output can stop a particular launch workflow.
• A script can fail during initialization or terminate mpv.
• An invalid screenshot directory matters only when a script or binding triggers a screenshot.
• A missing yt-dlp executable or inaccessible stream can prevent an online URL from loading, although --idle=yes should still permit an IPC-only test.
• A forced track selection can fail to produce the expected playback state, but it should not change the IPC address.

If the clean idle test works, restore these settings one category at a time. Stop as soon as the failure returns because the last restored category is the useful lead.

3. Check Paths, Permissions, Quoting, and Startup Timing

3.1 Correct Windows Named Pipe Syntax

A Windows endpoint should use the named pipe namespace:

\\.\pipe\mpv-ipc

Do not substitute a normal path such as C:\temp\mpv-ipc. Also remember that backslashes may require escaping inside programming-language strings. For example, the text passed to mpv must ultimately resolve to the named pipe path, regardless of how many escape characters appear in source code.

Use the same user account and privilege level for the initial test. Running mpv as administrator while the client runs normally, or the reverse, can complicate access and process discovery. Success means both programs use the same pipe identifier and the client opens it while mpv is alive.

3.2 Check Unix Socket Directory Permissions

On Linux and macOS, mpv must be able to create the socket in the parent directory, and the client must be able to access it. For a private test, use a directory owned by your account:

mkdir -p "$HOME/.cache/mpv-ipc"
mpv --no-config --idle=yes --input-ipc-server="$HOME/.cache/mpv-ipc/socket"

Inspect both the directory and socket:

ls -ld "$HOME/.cache/mpv-ipc"
ls -l "$HOME/.cache/mpv-ipc/socket"

A stale socket path from an abruptly terminated process can also interfere with a new launch. First verify that no mpv process is still using it. Then remove only that known test socket, not your configuration directory:

rm "$HOME/.cache/mpv-ipc/socket"

Restart mpv and check that it creates a fresh socket. Avoid placing the socket on a filesystem that does not support Unix domain sockets.

3.3 Quote Paths at the Shell Boundary

Spaces and shell-special characters can change the option before mpv receives it. Quote the complete argument value:

mpv --input-ipc-server="$HOME/Library/Application Support/mpv/ipc-socket" --idle=yes

In scripts, print or log the final argument list. The client must use the expanded path, not a literal string containing $HOME or ~ unless it performs expansion itself.

3.4 Start mpv Before the Client Connects

A client cannot connect before mpv creates the socket or pipe. Some clients try once and fail permanently, while others retry. Launch mpv first, wait until the endpoint is available, and then start the client.

For automation, implement bounded retries with a short delay rather than a fixed assumption that mpv initializes instantly. Also detect when mpv exits so the client does not retry forever. Success means the client consistently connects after endpoint creation, including on slower launches.

3.5 Account for Sandboxed Builds

Flatpak, Snap, and other sandboxed applications may see different filesystem paths or lack access to a socket created outside their permitted locations. The same issue can arise when mpv is sandboxed but the client is not, or when two sandboxed applications have separate views of the filesystem.

Place the Unix socket in a location accessible to both applications, or use the packaging system's supported permission controls. Do not broadly disable security boundaries as a first step. A useful diagnostic is to test trusted, non-sandboxed builds from the operating system's normal package source. If that works, investigate sandbox path sharing rather than mpv's JSON syntax.

4. Use mpv Diagnostics to Find the Failure Point

4.1 Read Terminal Output First

Launch mpv from a terminal instead of a desktop shortcut. Look for an error mentioning input-ipc-server, failure to bind or create a socket, an unknown option, or an early process exit. The first relevant error is usually more valuable than later cascading messages.

4.2 Increase Relevant Logging

Create a temporary log while running the clean test:

mpv --no-config --idle=yes --input-ipc-server=/tmp/mpv-test-socket --msg-level=all=v --log-file=mpv-ipc-test.log

On Windows, replace the socket value with the named pipe path. Review the log for the effective command, startup completion, IPC-related errors, script failures, and shutdown reasons. Logs may contain local paths or URLs, so remove sensitive information before sharing them.

Verbose logging is diagnostic, not a permanent fix. Once you identify the cause, return logging to its normal level.

4.3 Use Playback Diagnostics Only When mpv Exits

The stats overlay and track list help when the IPC problem occurs only with specific media. The stats overlay can show active decoding and output information, while the track list can confirm whether expected audio, video, and subtitle tracks were detected. These tools do not repair a missing socket, but they can reveal that mpv is alive and the apparent IPC failure is actually a command targeting an unavailable property or track.

If IPC works with --idle=yes but fails when opening one HDR file, high-bitrate stream, playlist, or online URL, test that media without forced hardware decoding, custom shaders, scripts, or external tools. GPU drivers, display servers, audio backends, network access, yt-dlp availability, and damaged media become relevant only in this media-dependent scenario.

5. Run a Clean Temporary Test Before Changing Many Options

A controlled test prevents unrelated mpv troubleshooting from obscuring the IPC issue. Use this sequence:

1. Close existing test instances and verify that no client is holding an obsolete endpoint.
2. Choose a new, unique socket or named pipe name.
3. Launch mpv with only --no-config, --idle=yes, and --input-ipc-server.
4. Confirm that mpv remains running.
5. Connect after the endpoint exists.
6. Send the newline-terminated get_property request for mpv-version.
7. Restore your normal config, scripts, profiles, and media arguments in small groups.

If the minimal test fails, focus on the endpoint value, operating system permissions, packaging, and the exact mpv binary being launched. If it succeeds, stop changing operating system settings. The fault is more likely in the regular launcher, client configuration, startup order, or restored mpv customization.

When a specific script causes the failure, disable only that script and inspect its documented dependencies and logs. When one stream or file causes mpv to exit, test another known-good local file. This distinguishes an IPC transport problem from a media-specific failure without destroying a working setup.

6. Quick Fix Checklist

• Launch mpv with --no-config --idle=yes and an explicit IPC endpoint.
• Use \\.\pipe\name for a Windows named pipe.
• Use a writable, accessible Unix socket directory on Linux or macOS.
• Make the client and mpv use exactly the same endpoint.
• Start the client only after mpv has created the endpoint.
• Send valid, newline-terminated JSON.
• Test get_property with mpv-version before media-dependent commands.
• Check shell and programming-language escaping separately.
• Run both programs under compatible user and sandbox permissions.
• Inspect terminal output and a temporary verbose log if mpv exits early.
• Restore scripts, profiles, shaders, hwdec, and media options gradually.
• Stop changing settings once the basic property query succeeds.

7. Frequently Asked Questions

7.1 Why does the IPC client report connection refused?

The endpoint may not exist yet, mpv may have exited, or the client may be using the wrong path. Start mpv first, confirm the socket on Unix, and verify the full pipe name on Windows. If a clean idle launch remains open and the client still fails, compare the exact endpoint strings received by both processes.

7.2 Can a client connect before mpv starts?

Not immediately. The server endpoint exists only after mpv initializes it. A supervising client can start first only if it waits and retries after launching mpv. Retries should have a timeout and should stop if the mpv process exits.

7.3 Why can the client connect but receive no response?

The command may be invalid JSON, missing its terminating newline, or using an unsupported command shape. Send {"command":["get_property","mpv-version"]} followed by a newline. Also ensure the client reads complete newline-delimited responses instead of waiting for the connection to close.

7.4 Do subtitle, HDR, hwdec, or audio settings break IPC?

They do not normally control the IPC server. They matter when they make mpv fail, hang, or exit during media initialization. If IPC works in idle mode, load a known-good file and restore those settings one group at a time.

7.5 Why does IPC work from a terminal but not from my application?

The application may launch another mpv binary, use a different working directory, omit an argument, escape backslashes incorrectly, start too early, or run inside a sandbox. Log the final executable path and argument list from the application, then compare them with the successful terminal command.

7.6 Should I delete my mpv configuration folder?

No. First use --no-config for a temporary test. If that succeeds, disable or move individual scripts and options in small groups. Preserving the original configuration makes it easier to identify the actual conflict and avoids unnecessary loss of profiles, bindings, and carefully tuned settings.