Troubleshooting Guide
This guide helps you resolve common issues when using Git-based Source Control in Nected. If your problem isn’t covered here, pull before pushing, confirm your PAT and branch access, and use GitHub for merge and conflict resolution.
Connection & authentication
Cannot connect to the repository
Symptoms: "Failed to connect", "Invalid repository URL", or connection timeout when connecting or syncing.
What to check:
Repository URL
Use the correct HTTPS or SSH URL from GitHub (e.g.
https://github.com/org/repo.gitor[email protected]:org/repo.git).Ensure the repo exists and you have access in GitHub.
Network & firewall
If you use an On-Premise Agent or corporate network, ensure outbound HTTPS (and SSH if used) to
github.comis allowed.Proxies or VPNs can block Git; try from a different network to isolate.
Repository immutability
The connected repository cannot be changed after setup. If you need a different repo, you must use a workspace where the correct repo was connected from the start.
Learn how to connect with GitHub
Personal Access Token (PAT) errors
Symptoms: "Authentication failed", "403 Forbidden", "Bad credentials", or "Token expired" when pushing or pulling.
What to do:
Token validity
PATs can expire or be revoked. Create a new Fine-grained or Classic PAT in GitHub and add it in Nected via Git Repository → Add Personal Token (or update the existing token if your UI allows).
Token permissions
Fine-grained PAT: Repository Contents → Read and Write for the specific repo.
Classic PAT:
reposcope (Read and Write).Ensure the token is for the same GitHub account that has access to the connected repository.
Where to add the token
Primary admin: Token is set during Connect to Git.
Additional admins: Git Repository → Add Personal Token; they do not reconfigure the repo URL.
Branch protection
If you get 403 only on certain branches, GitHub branch protection may be blocking direct pushes. Use a branch you’re allowed to push to, or use PRs and merge in GitHub, then pull in Nected.
"Repository is immutable" / Wrong repository connected
Symptoms: You need to use a different GitHub repository, but Nected doesn’t allow changing the connected repo.
Explanation: The connected repository is fixed per workspace for consistency and auditability.
Options:
Use a workspace that was connected to the correct repository from the start, or
Connect the correct repository when creating or configuring a new workspace.
Branches
I don’t see a branch / Can’t switch to a branch
Symptoms: A branch exists in GitHub but doesn’t appear in Nected, or you can’t switch to it.
What to check:
GitHub access
Branch visibility in Nected follows your GitHub permissions. You only see branches you have access to in the connected repo.
Ask a repo admin to add you as a collaborator or to give your team access to the branch.
Fine-grained PAT
If using a Fine-grained PAT, it must be scoped to the repository that contains the branch. Broader org-level permissions may still be required depending on your GitHub setup.
Refresh
After new branches or permissions are granted in GitHub, try switching branch again or refreshing the Git panel in Nected.
Default branch is wrong / Can’t change default branch
Symptoms: You want a different default branch (e.g. main instead of master), but you can’t change it.
Explanation: Only the primary workspace admin (workspace owner or first admin who connected Git) sets the default branch, and only during initial Git setup.
What to do:
If you’re the primary admin and the repo was just connected, set the correct default branch when prompted.
If the repo is already connected, the default branch cannot be changed in Nected; use a workspace where the correct default was set at connection time, or reconnect in a new workspace with the desired default.
Push & commit
Push conflict: "Workspace differs from GitHub"
Symptoms: When pushing, Nected shows that your workspace and the remote branch have diverged (e.g. someone else pushed, or you changed branch/state).
Your options in Nected:
Override and Push
You intend to replace the remote branch with your current workspace state. Use only when you’re sure you want to overwrite remote changes.
Discard Changes
Cancel the push and keep your current local state.
If you need to merge instead of overwrite:
Resolve conflicts in GitHub (e.g. pull on another clone, fix conflicts, commit, push).
In Nected, click Pull to bring the updated branch (including the merge) into your workspace.
Nected does not perform merge conflict resolution; GitHub is the source of truth for merging.
Learn about handling push conflicts
Nothing to push / Changes not appearing in push dialog
Symptoms: You edited rules, workflows, or other entities but the push panel shows no changes or an empty list.
What to check:
Branch
Confirm you’re on the intended branch. Changes are per-branch; switching branches loads that branch’s state.
Last sync
Push only includes changes since the last push or pull. If you just pulled and made no further edits, there may be nothing to push.
Entity type
Only Synced Entities are tracked: Rules, Workflows, Integrations, Datasets, Variables (and related versions). Schedulers, workspace settings, and similar are not synced and won’t appear.
Save
Nected auto-saves, but if you had errors or left the editor before save completed, changes might not be included. Re-open the resource, confirm it’s saved, then try Push again.
Force push (Override and Push) overwrote remote changes
Symptoms: You or a teammate used Override and Push and important commits on the remote branch were replaced.
Prevention: Prefer normal Commit and Push. Use Override and Push only when you intentionally want the remote branch to match your current workspace.
Recovery: If the overwritten commits were pushed to GitHub recently, you may be able to recover them via GitHub’s commit history or reflog on a clone that still has the old state. Restore the desired state in GitHub (e.g. revert or reset and force push from a clone), then Pull in Nected to realign the workspace.
Pull & sync
Pull shows "No changes" but GitHub has new commits
Symptoms: You merged a PR or pushed from another machine, but Nected’s Pull says there are no changes.
What to check:
Branch
Ensure you’re on the same branch in Nected that was updated in GitHub (e.g.
main).
Caching / refresh
Try closing and reopening the Pull dialog, or refreshing the Git panel, then run Pull again.
GitHub state
In GitHub, confirm the commits are on the branch you’re pulling and that the merge actually completed.
Pull fails or stops at "Sync Integrations & Credentials"
Symptoms: Pull doesn’t complete; it asks you to fix Integrations or credentials.
Explanation: Pulled rules and workflows can reference Integrations that don’t exist in your workspace or lack credentials. Credentials are never in Git; they must be configured in Nected.
What to do:
In the Pull flow, complete Step 2 — Sync Integrations & Credentials.
For each missing or invalid Integration:
Create the Integration in Nected if it’s new, or
Map the reference to an existing Integration and ensure credentials (and any config) are set.
Retry the pull after all Integration/credential issues are resolved.
Pull conflicts: Merge vs Override vs Archive
Symptoms: Nected reports conflicts during pull and offers Merge & Pull, Override & Pull, or Archive / Archive Overwrite.
What to choose:
Merge & Pull
You want to keep both remote and local changes where possible. Nected merges automatically where it can.
Override & Pull
You want the workspace to match the remote branch exactly; local-only changes for conflicting entities will be replaced.
Archive / Archive Overwrite
You want to keep the remote version but preserve the local one as archived (exact behavior depends on your Nected version).
Resolve any remaining conflicts as prompted; then the Git panel should show the branch as in sync.
Sync status (Ahead / Behind / Ahead & Behind)
Meanings:
Ahead
Your workspace has local commits/changes not yet pushed to the remote branch.
Behind
The remote branch has commits you don’t have. Pull to update.
Ahead & Behind
Workspace and remote have diverged (both have unique commits). Pull first (or resolve in GitHub), then push if needed.
If status seems wrong:
Pull to get the latest from the branch, then check again.
Confirm you’re on the correct branch and that no one else force-pushed; that can change history and make local state invalid until you pull (or reset).
Integrations & credentials after sync
Integrations missing or broken after pull
Symptoms: After pulling, rules or workflows fail with errors about missing Integrations or invalid configuration.
Explanation: Git stores Integration names and metadata only, not credentials or sensitive configuration. Each environment (e.g. staging, production) must have Integrations created and configured in Nected.
What to do:
During Pull, complete Step 2 — Sync Integrations & Credentials and Step 3 — Update Missing Configs.
In Nected, open Integrations and ensure every Integration referenced by the pulled logic exists and has valid credentials and config for this environment.
Re-run or re-publish the affected rules/workflows after fixing Integrations.
Variables or secrets not syncing
Symptoms: Variable names appear after pull but values are empty or prompts ask for secrets.
Explanation: By design, variable and secret values are not stored in Git; only names (and non-sensitive metadata) are synced. This avoids exposing secrets in the repository.
What to do: After pull (or when switching branches), set variable values and secrets in Nected for the current workspace/environment. Use Nected’s Variables and Secrets UI (or your org’s secret management) to fill them in.
Schedulers & Git
Symptoms: Schedules don’t appear in Git or don’t run on a non-default branch.
Explanation: Schedulers are not part of Git sync. They exist only in the Nected workspace and run only on the default branch (e.g. main or master). They are not versioned or merged via Git.
What to do: Manage schedulers in Nected. If you need schedule changes to follow a process, document them outside Git (e.g. runbooks or internal docs). When you switch to a non-default branch, expect that schedules are not active for that branch.
On-Premise Agent
Symptoms: Git or Source Control options are missing or disabled.
Check: Source Control requires On-Premise Agent v1.0.5 or newer. Upgrade the agent to at least v1.0.5 and ensure the agent can reach GitHub (and your Git provider if different) for push/pull.
Getting more help
Git workflow (PRs, merges, conflict resolution): Use GitHub’s documentation and your team’s branching policy.
Nected lifecycle: See Overview and Commit & Push.
Branches and PATs: See Branches and Setup (GitHub).
If the issue persists, contact Nected support with your workspace details, branch name, and whether the problem occurs on push, pull, or connection (and any on-screen error message).
Last updated