Troubleshooting

Table of contents

  1. Reading error messages
  2. Common issues
    1. “No workspace folder found”
    2. Auth fails or credentials are rejected
    3. Pull fails with a network error
    4. Push is blocked by a conflict
    5. “another command is already running” warning appears unexpectedly
    6. Index is out of sync / push behaves unexpectedly
    7. Invalid .snsyncrc setting blocks pull commands
    8. OAuth token expired / refresh fails
  3. Error categories
  4. Filing a bug report

Reading error messages

sn-sync error messages follow this format:

<prefix> (<ERROR_CODE>) <details>

Examples:

  • Pull failed: (SN_PULL_ALL_FILES_FAILED) network timeout
  • Push active failed: (SN_PUSH_CURRENT_FAILED) remote conflict against baseline

For more detail, open the VS Code output channel sn-sync diagnostics:

  1. Go to View → Output
  2. Select sn-sync diagnostics from the dropdown

The diagnostics channel logs structured entries with the error code, command, category, and timestamp. Sensitive values (passwords, tokens) are always redacted before logging.

Common issues

“No workspace folder found”

Cause: VS Code is open without a folder or workspace.

Fix: Open a folder (File → Open Folder) and retry the command.

Auth fails or credentials are rejected

Fix:

  1. Run sn: auth → validate auth to test current credentials
  2. If validation fails, run sn: auth → configure auth and re-enter credentials
  3. Confirm your instance URL is HTTPS and the host matches *.service-now.com (or your configured allowed host)

Pull fails with a network error

Cause: Instance unreachable, VPN required, wrong instance name, or firewall blocking the connection.

Fix:

  1. Confirm you can reach https://<instance>.service-now.com in your browser
  2. Verify the instance name in .snsyncrc
  3. Connect to VPN if required by your organisation
  4. Run sn: auth → validate auth to confirm auth is working

Push is blocked by a conflict

Cause: The remote record changed since your last pull.

Fix: Run sn: push → all files. For each conflicting file, choose one of:

Action When to use
overwrite remote You are confident your local version is correct
discard local You want to accept the remote version and abandon local changes

“another command is already running” warning appears unexpectedly

Cause: Only one sn-sync command can run at a time — this is intentional, to avoid concurrent reads/writes to the sync index and local files. If you see this warning, either:

  • Another sn-sync command is genuinely still running (for example, an input box is still open and waiting for your response — it will not close on its own if you click away).
  • You are running an old, cached build of the extension that predates a fix to this lock (see below).

Fix:

  1. Check for any pending sn-sync prompt (input box or quick pick) still open in VS Code and respond to it or press Escape to cancel it — the lock is only released once that prompt is answered.
  2. If no prompt is open and the warning still appears, reload the VS Code window (Cmd/Ctrl+Shift+P → Developer: Reload Window) to rule out a stuck extension host state.
  3. If the warning appears every time you use sn: pull or sn: push (the scope-selector commands) even with nothing else running, confirm your installed sn-sync version is 0.1.4 or later, which fixes a self-blocking bug in these dispatcher commands.

Index is out of sync / push behaves unexpectedly

Cause: The sync index no longer reflects the actual state of local files.

Fix:

  1. Run sn: reset → reset index
  2. Run sn: pull → all files to rebuild the index from the remote state

Invalid .snsyncrc setting blocks pull commands

Cause: A settings entry in .snsyncrc is invalid — for example it is missing folder, table, or key, has no valid fields, or defines multiple fields that share the same extension (which would generate duplicate output file names for the same record).

sn-sync never silently rewrites or removes invalid entries from .snsyncrc. Instead, pull commands (pull all files, pull table, pull by sys_id, pull current) fail fast with an error identifying the problematic setting.

Example error:

Invalid sync setting in .snsyncrc for table "sys_dictionary": duplicate output file names would be generated for key "name" (extensions: txt, txt, txt). Give each field a unique "extension" so pulled files do not overwrite each other.

Fix:

  1. Open .snsyncrc and find the setting identified in the error (by folder and/or table).
  2. Fix the reported problem — for example give each fields entry a unique extension, or add the missing folder/table/key value.
  3. Save the file and re-run the pull command.

OAuth token expired / refresh fails

Fix:

  1. Run sn: auth → validate auth
  2. If validation fails, run sn: auth → configure auth and complete the OAuth flow again

Error categories

When looking at the sn-sync diagnostics output, the category field helps you decide where to look first:

Category Typical cause First step
auth Invalid, expired, or missing credentials Re-run sn: auth
network Instance unreachable or timed out Check connectivity and instance name
conflict Remote record changed since last pull Pull, resolve conflict, retry push
validation Bad input (sys_id, table name, config value) Check command inputs and .snsyncrc
unknown Unexpected error Check full diagnostics and open a bug report

Filing a bug report

If the issue persists, open a bug report at github.com/AlexAlvarez092/sn-sync/issues.

Include:

  1. The full error message (with error code)
  2. The command that failed
  3. Extension version (visible in the Extensions panel)
  4. VS Code version and operating system
  5. The relevant sanitised line from the sn-sync diagnostics output channel