Remote Mac launchd Scheduled Tasks Not Running? 2026 Troubleshooting Guide
📋 Table of Contents
Symptom → fastest fix: A remote Mac script works over SSH but not on schedule? First identify whether it needs a user session; then match the launchd job type to that requirement and test its account, environment, and actual output.
This applies if you maintain scheduled scripts, build jobs, or background work on a remote Mac. It is for independent developers, DevOps engineers, and platform maintainers diagnosing a gap between an SSH command and an automatic run.
SSH success vs scheduled execution
A successful manual command proves only that the script can run in your SSH shell under its current conditions. It does not prove that launchd runs it with the same account, environment variables, working directory, permissions, or login-session resources. Apple describes launchd jobs as managed services with their own configuration and execution context; its overview of scheduled jobs is a useful boundary, not evidence that your particular job completed.
Start by gathering evidence rather than rewriting code. Record the exact command that works over SSH, the job’s configured program and arguments, the account that owns the job, and the output files or logs expected from a run. If no expected output appears, check the job’s standard output and error destinations before concluding that launchd never started it.
| What you observe | What it establishes | What to check next |
|---|---|---|
| The command works when typed in SSH | The command can run in that shell context | Account, environment, working directory, file access |
| The job appears in its configured or loaded state | Configuration has been read or the job is registered | A real trigger, process activity, and fresh output |
| A log file exists but has not changed | The file was created at some point | Timestamp, append behavior, destination permissions |
| Output is produced only after you log in | The task may depend on a user session or user-owned resources | Agent versus daemon scope and session requirements |
Apple’s Terminal guide to managing scripts with launchd covers the relationship between scripts and launchd. Use it alongside your own task configuration: a script’s success in Terminal is not a substitute for observing an automatic run.
User agent vs system daemon
Choose task scope based on the work’s dependencies, not on which setting seems more powerful. Apple distinguishes user agents from system daemons by their role and execution context in its documentation on daemons and agents. Its system-context documentation also explains that user sessions and the system context are not interchangeable.
| Task requirement | Likely fit | Evidence to collect before deciding |
|---|---|---|
| Uses a particular user’s files, settings, or session resources | User agent | Confirm the job belongs to that account and can access each required path |
| Must run without relying on a logged-in user | Consider a system daemon, if the work supports that context | Confirm the execution account, required permissions, and resource access |
| Needs a graphical application or interactive state | User-session-bound workflow, or redesign | Identify which operation requires the session and test whether it can be replaced |
| Only needs a command-line tool and explicit input files | Choose scope by ownership and startup needs | Run a minimal test with explicit paths and capture its output |
A system daemon is not a universal fix for a user agent that fails. Apple’s description of daemon design and execution context gives you a basis for assessing whether work belongs in the system context. Keep permissions no broader than the task requires, and verify that the selected account can reach each needed file, network resource, and credential.
For example, a script that processes a project directory owned by one developer may be a poor fit for a system-level job if that job cannot access the directory as configured. Conversely, an unattended command that needs no user-specific state may not need to wait for an interactive login. Make the choice from observed requirements, not from the fact that one job type sounds more server-like.
Headless work vs session-bound work
Before treating a task as unattended background work, list every operation it performs. A script may call a graphical application, expect a dialog, read a setting from the logged-in account, or depend on credentials available only in that user’s context. Each dependency changes what you can expect from an automatic run.
| Dependency | Why SSH success may mislead | How to test the boundary |
|---|---|---|
| Graphical application | An SSH command does not itself prove the scheduled process has an appropriate graphical session | Isolate the GUI-dependent operation and test it under the intended login conditions |
| Interactive authentication | A prompt cannot be answered by an unattended run in the same way as a person at a terminal | Replace the prompt with an approved noninteractive flow, or keep the job session-bound |
| User-specific credential | Availability may depend on the account and its session state | Test the exact account and credential access path used by the job |
| User interface state | A script may assume a window, application, or logged-in desktop is ready | Remove that assumption or make the session requirement explicit |
Do not put secrets directly into a property list or a shell command just to make a scheduled run succeed. Apple’s Keychain Services documentation explains the system’s credential-storage APIs, but you still need to test whether the job’s account and context can access the required item. If the task depends on a person responding to a prompt, it is not a fully unattended task until that interaction is removed or handled through a suitable workflow.
The decision is not simply “GUI or no GUI.” Ask whether each operation can run with the resources available under the chosen account and session. If you cannot reproduce the required state during a scheduled test, record the task as session-dependent and change the execution boundary rather than granting broad permissions or repeatedly reloading the same job.
Shell environment vs launchd environment
SSH shells often load user-specific setup. An automatic job should not be assumed to receive those same settings. The practical failure pattern is simple: a command is available by name in your interactive shell, but the job cannot locate it; or the script expects a working directory that is not present when it starts.
Apple’s guide to shell script basics in Terminal can help you inspect what the script invokes. For the scheduled version, make the required inputs explicit and use the job’s own logs as evidence.
Check these items in order:
- Executable path: Record the path to each command the script calls. Test with that explicit path instead of relying on a shell search path.
- Arguments and quoting: Compare the configured program and its arguments with the command you type over SSH. Keep arguments separate and check that paths containing spaces are handled correctly.
- Working directory: Identify every relative path in the script. Replace assumptions about the current directory with explicit paths, or verify the job starts in the required location.
- Environment variables: List the variables the script reads. Set required values for the job instead of assuming interactive shell configuration is imported.
- Permissions and inputs: Confirm that the execution account can read inputs, write outputs, and reach any required external resource.
- Logs: Route standard output and errors to locations that the job’s account can write to, then inspect fresh entries from the scheduled attempt.
Apple’s Terminal instructions for script management provide launchd context; your job’s captured output provides the evidence for your specific failure. Change one assumption at a time. A minimal script that writes a timestamp and exits can distinguish a launch problem from a failure inside a larger build or maintenance script.
Loaded job vs proven execution
A property list on disk, a successful load operation, or an apparent job registration does not confirm that the intended work completed. Validate the whole path: trigger, process, exit, and useful output. Apple’s documentation on creating launchd jobs describes job configuration; your acceptance test must go further and confirm the task’s result.
Use this checklist before you declare the issue fixed:
- [ ] Record the job’s owner and decide whether it needs a user agent or a system daemon.
- [ ] Write down every required file, command, environment variable, credential, and external resource.
- [ ] Run the script with explicit paths and capture its standard output and errors.
- [ ] Trigger the configured job under the intended account and login conditions.
- [ ] Confirm a fresh completion record and verify the output content, not just the output file’s existence.
- [ ] Test the relevant restart or login condition and repeat the result check.
- [ ] Document dependencies that prevent the job from running without a user session.
For restart testing, distinguish what you are trying to prove. If the task should run after a user signs in, verify it under that login condition. If it should start without a user session, verify that requirement under the intended system-startup conditions. For a scheduled trigger, verify a new run from that trigger and inspect its result. Apple’s materials on job scheduling describe launchd’s scheduling role, but they do not prove that your script’s own dependencies are present after a restart.
| Acceptance question | Pass evidence | If evidence is missing |
|---|---|---|
| Did the intended trigger occur? | A fresh run record tied to the trigger you tested | Recheck the trigger and job configuration |
| Did the process start under the intended account? | A process or log record tied to that account | Revisit job ownership and execution scope |
| Could it access its dependencies? | Successful reads, credential access, and external-resource checks | Narrow the missing dependency and test it directly |
| Did the task complete correctly? | Expected output content and a completion record | Treat the job as unverified, even if it loaded |
| Does the restart behavior match the requirement? | A successful run under the required startup or login condition | Adjust the task boundary or use a workflow that fits |
FAQ: common remote Mac launchd failures
Why does launchd work over SSH but fail automatically?
SSH runs your command in a remote shell with its own account, environment, and session. launchd may run the job with different conditions. Compare the job’s account, paths, environment, permissions, and session dependencies, then capture the scheduled attempt’s output. If the script depends on a prompt or GUI state, fix that boundary before changing unrelated code.
Should I choose a LaunchAgent or a LaunchDaemon?
Use a user agent when the task belongs to a user or depends on that user’s session or resources. Consider a system daemon only when the work can run without that session and its account can access the required resources. Verify the task’s actual dependencies first. Switching to a system context can change access and behavior; it does not automatically repair a script that expects user-specific state.
What if a scheduled job needs a GUI or login?
Identify the exact operation that needs the desktop, user login, or interactive authentication. If you can replace it with a noninteractive operation and an appropriately accessible credential, test that redesigned flow under the job’s account. If the operation genuinely requires a user session, keep it tied to that session or choose another workflow rather than treating it as unattended system work.
How do I know the job works after restart?
Test the condition the job is meant to support: system startup without a user, a user’s login, or a scheduled trigger. Then confirm that a fresh run completed and produced the expected result. A job file or loaded state is not enough. Check logs and resource access after the test, and document any login dependency so operators know when the task is expected to run.
If the script needs macOS tools that a Linux server cannot provide, or a machine that stays reachable when your workstation is off, compare the execution requirement before changing infrastructure. A local Mac can sleep or become unavailable when its owner is away; a generic Linux host does not provide a macOS environment; and a virtualized setup still needs its own compatibility and session testing. For a temporary or test workload, a remotely accessible Mac can avoid buying and maintaining a dedicated machine, but it is not the right answer for every job. If you need sustained, predictable heavy use or physical access to local hardware, evaluate an owned Mac instead. You can review the remote Mac environment and access options and compare bare metal with macOS virtualization before deciding. Rent from MacDate only if the task’s account, login, resource, and restart requirements pass the same acceptance checks on the environment you plan to use.