What causes "post-auth hook failed: %w" in router-for-me/CLIProxyAPI?

Inspect the wrapped error — it comes from the hook implementation, not from storage

post-auth hook failed: %w

Error message

post-auth hook failed: %w

What it means

The pre-save hook h.postAuthHook, run by saveTokenRecord before store.Save, returned an error, so the credential record was not persisted. This hook is wired by the host application/SDK to perform side effects such as config sync or notification before a token lands on disk; its failure is treated as fatal for the save.

Source

Thrown at internal/api/handlers/management/auth_files_fields.go:746

	}

	if len(existingMap) > 0 {
		coreauth.MergeExistingAuthMetadata(record, existingMap)
	}
}

func (h *Handler) saveTokenRecord(ctx context.Context, record *coreauth.Auth) (string, error) {
	if record == nil {
		return "", fmt.Errorf("token record is nil")
	}
	h.mergeExistingAuthFileMetadata(record)
	store := h.tokenStoreWithBaseDir()
	if store == nil {
		return "", fmt.Errorf("token store unavailable")
	}
	if h.postAuthHook != nil {
		if err := h.postAuthHook(ctx, record); err != nil {
			return "", fmt.Errorf("post-auth hook failed: %w", err)
		}
	}
	savedPath, errSave := store.Save(ctx, record)
	if errSave != nil {
		return savedPath, errSave
	}
	if h.postAuthPersistHook != nil {
		if errHook := h.postAuthPersistHook(ctx, record); errHook != nil {
			return savedPath, fmt.Errorf("post-auth persist hook failed: %w", errHook)
		}
	}
	return savedPath, nil
}

View on GitHub (pinned to 78f0c4079e)

Solutions

Inspect the wrapped error — it comes from the hook implementation, not from storage
Fix whatever the hook needs (writable config path, reachable dependency) based on its own error text
If the hook's failures should be non-fatal, change it to return nil on soft errors or make it skippable by configuration
Retry the save; nothing was persisted, so the operation is safe to repeat

Defensive patterns

Strategy: try-catch

Try / catch

if _, err := h.saveTokenRecord(ctx, record); err != nil {
    if strings.HasPrefix(err.Error(), "post-auth hook failed") {
        // nothing persisted; fix the hook dependency, then retry the save safely
    }
}

Prevention

Keep post-auth hooks idempotent and dependency-light
Log hook errors with enough context to identify the failing side effect
Make optional hook failures configurable to skip instead of abort

When it happens

Trigger: Completing an OAuth login or saving an auth record when the registered post-auth hook fails — e.g. a hook that writes to config.yaml hitting a permissions error, or a hook validating provider state and rejecting the record.

Common situations: Custom embedders adding hooks that touch the filesystem or external services; config dir read-only in containers; hook logic version-skew after upgrading the SDK.

Related errors

AI-assisted analysis of router-for-me/CLIProxyAPI@78f0c4079e (2026-08-15). Data as JSON: /api/errors/8a6a4d82c0c1a37c. Report an issue: GitHub.