Update commit failed (files may be staged but not committed)

Error message

Update commit failed (files may be staged but not committed).
    Error: ${e.message.split('\n')[0]}
    Please run manually to finish the update:
    ${recovery}

What it means

The final step of `update-system.mjs apply` commits the staged system files (chore: auto-update system files to vX.Y.Z). If `git commit` fails while the changed paths are still staged (confirmed via git status), apply throws this error with a ready-to-copy recovery command that matches the strategy actually used: a plain commit after an index-wide stage, or a pathspec commit when paths were staged individually — the pathspec form preserves staged file modes, so suggesting the wrong one would quietly reintroduce the bug it recovers from.

Source

Thrown at update-system.mjs:2176

        const entries = gitStatusEntries();
        const changedPaths = new Set(entries.map(entry => entry.path));
        const allTargetPaths = [...pathsToStage, ...materializedSkillEntrypoints];
        commitFailed = allTargetPaths.some(p => changedPaths.has(p));
      } catch (err) {
        commitFailed = true;
      }

      if (commitFailed) {
        const allTargetPaths = [...pathsToStage, ...materializedSkillEntrypoints];
        const pathspec = allTargetPaths.map(p => `'${p.replace(/'/g, "'\\''")}'`).join(' ');
        // Print the command matching the path actually taken. Suggesting the
        // pathspec form after the index form was selected would tell the user to
        // run the very thing that drops the staged mode bits — a recovery step
        // that quietly reintroduces the bug it is recovering from.
        const recovery = usedIndexCommit
          ? `git commit -m "chore: auto-update system files to v${remote}"`
          : `git commit -m "chore: auto-update system files to v${remote}" -- ${pathspec}`;
        throw new Error(
          `Update commit failed (files may be staged but not committed).\n` +
          `    Error: ${e.message.split('\n')[0]}\n` +
          `    Please run manually to finish the update:\n` +
          `    ${recovery}`
        );
      }
      // Otherwise, genuinely nothing to commit (already up to date)
    }

    // Verify the update actually produced a coherent install before claiming
    // success. A client whose local manifest predates the target checks out
    // only the paths ITS OWN manifest lists, so everything added upstream since
    // is silently absent and the next script dies with ERR_MODULE_NOT_FOUND.
    // Re-running apply fixes it (the first pass did update update-system.mjs
    // itself, so the second pass uses the target manifest) — but only if the
    // user is told, instead of being shown "Update complete" (#1998).
    const unmaterialized = missingFromTargetManifest(remoteSystemPaths);
    if (unmaterialized.length > 0) {

View on GitHub (pinned to 60398d6549)

Solutions

Run the exact `git commit ...` command printed in the error — the files are already staged
If the underlying error was missing identity: git config --global user.name 'Your Name' and user.email, then run the recovery commit
If a hook rejected it, read the hook output and fix or consciously bypass with --no-verify before committing
Verify afterwards with `git log -1` and `git status`

Example fix

git config --global user.name 'Your Name'
git config --global user.email 'you@example.com'
git commit -m "chore: auto-update system files to v1.9.0"

Defensive patterns

Strategy: validation

Validate before calling

import { execSync } from 'child_process';
const hasIdentity = (() => { try { execSync('git config user.email', { stdio: 'pipe' }); return true; } catch { return false; } })();
if (!hasIdentity) throw new Error('configure git user.name and user.email before running the updater');

Prevention

Configure git identity on every new machine/CI runner before first update
Keep pre-commit hooks from blocking automated maintenance commits (or allowlist them)
Expect one 'chore: auto-update system files' commit per update in your history

When it happens

Trigger: No git identity configured (user.name/user.email unset, git aborts with 'Please tell me who you are'); a pre-commit hook (husky, pre-commit framework) rejecting the auto-commit; index.lock held by a concurrent git process; detached HEAD or read-only .git.

Common situations: Fresh machines and CI runners that never ran git config; hook managers intercepting maintenance commits; users who never let tooling commit.

Related errors

AI-assisted analysis of santifer/career-ops@60398d6549 (2026-08-20). Data as JSON: /api/errors/83e98e91c9ce37ee. Report an issue: GitHub.