How to Fix macOS launchd Plist Errors — Services Not Starting

In this tutorial, you'll learn about How to Fix macOS launchd Plist Errors. We cover key concepts, practical examples, and best practices.

The Problem

Your launchd service is not starting:

launchctl: Could not load service: Operation not permitted

or:

Service is loaded but does not run.

Quick Fix

Step 1: Create a valid plist

WRONG — malformed plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.myapp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/myapp</string>
    </array>
</dict>
</plist>

RIGHT — complete plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.myapp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/myapp</string>
        <string>--daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/var/log/myapp.log</string>
    <key>StandardErrorPath</key>
    <string>/var/log/myapp.log</string>
</dict>
</plist>

Step 2: Place in the correct directory

# User agents:
~/Library/LaunchAgents/com.example.myapp.plist

# System daemons (requires root):
/Library/LaunchDaemons/com.example.myapp.plist

Step 3: Load the service

launchctl load ~/Library/LaunchAgents/com.example.myapp.plist

# Or start without loading permanently:
launchctl start com.example.myapp

Step 4: Check the service status

launchctl list | grep myapp

Output:

PID    Status  Label
1234   0       com.example.myapp

Status 0 means the last exit was successful. Non-zero means an error.

Step 5: Fix permission issues

chmod 644 ~/Library/LaunchAgents/com.example.myapp.plist
chown root:wheel /Library/LaunchDaemons/com.example.myapp.plist

Step 6: View logs

# Open the log file:
cat /var/log/myapp.log

# Or use:
log show --predicate 'process == "myapp"' --last 1h

Prevention

• Validate plist syntax: plutil -lint ~/Library/LaunchAgents/*.plist.
• Use absolute paths in ProgramArguments.
• Start with RunAtLoad for services that should start at login.

Common Mistakes with launchd plist

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

These mistakes appear frequently in real-world MACOS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ