gravitational/teleport · warning

PID files are not supported on Windows

Error message

PID files are not supported on Windows

What it means

CreateLockedPIDFile writes a PID file with an exclusive advisory lock so other tooling can signal or inspect the process. On Windows builds this feature is unimplemented and the function is a stub that always returns this error, so any Teleport service started with PID file logging enabled on Windows will fail at startup.

Source

Thrown at lib/utils/process/pid_windows.go:28

 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package process

import "errors"

// CreateLockedPIDFile creates a PID file in the path specified by pidFile
// containing the current PID, atomically swapping it in the final place and
// leaving it with an exclusive advisory lock that will get released when the
// process ends, for the benefit of "pkill -L".
func CreateLockedPIDFile(pidFile string) error {
	return errors.New("PID files are not supported on Windows")
}

View on GitHub (pinned to 1283425b60)

Solutions

1. Remove the pid_file configuration when running on Windows.
2. Run the service on Linux/macOS where CreateLockedPIDFile is implemented.
3. If PID tracking is required on Windows, implement process supervision via the Windows service control manager instead.

Example fix

// before (config)
pid_file: /var/run/teleport.pid
// after (Windows)
# pid_file omitted — not supported on Windows

if err := utils.CreateLockedPIDFile(pidFile); err != nil {
    if runtime.GOOS == "windows" {
        log.Info("PID file not supported on Windows; continuing without it")
        return nil
    }
    return trace.Wrap(err)
}

When it happens

Trigger: Calling CreateLockedPIDFile (directly or via service startup code) in a binary compiled for Windows, or running Teleport on Windows with pid_file configured.

Common situations: Porting a Linux service config to Windows unchanged; CI/test harnesses that exercise service bootstrap code on Windows; cross-compilation surprises where the pid_windows.go stub is linked in.

Related errors

• unexpected nil response from GetAssertion
• unexpected nil response from MakeCredential
• webauthn error code %v and syscall err: %v
• webauthn error code %v
• failed to retrieve stdout mode: %w

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/998739ebbb36ef10. Report an issue: GitHub.