# 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:**

1. **Repository URL**
   * Use the correct HTTPS or SSH URL from GitHub (e.g. `https://github.com/org/repo.git` or `git@github.com:org/repo.git`).
   * Ensure the repo exists and you have access in GitHub.
2. **Network & firewall**
   * If you use an On-Premise Agent or corporate network, ensure outbound HTTPS (and SSH if used) to `github.com` is allowed.
   * Proxies or VPNs can block Git; try from a different network to isolate.
3. **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](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/setup/github)

***

#### Personal Access Token (PAT) errors

**Symptoms:** "Authentication failed", "403 Forbidden", "Bad credentials", or "Token expired" when pushing or pulling.

**What to do:**

1. **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).
2. **Token permissions**
   * **Fine-grained PAT:** Repository **Contents → Read and Write** for the specific repo.
   * **Classic PAT:** `repo` scope (Read and Write).
   * Ensure the token is for the same GitHub account that has access to the connected repository.
3. **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.
4. **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:**

1. **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.
2. **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.
3. **Refresh**
   * After new branches or permissions are granted in GitHub, try switching branch again or refreshing the Git panel in Nected.

[Learn how branch access works](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/branches)

***

#### 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:**

| Option                | When to use                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **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:**

1. Resolve conflicts in **GitHub** (e.g. pull on another clone, fix conflicts, commit, push).
2. 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](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/commit-and-push#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:**

1. **Branch**
   * Confirm you’re on the intended branch. Changes are per-branch; switching branches loads that branch’s state.
2. **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.
3. **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.
4. **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:**

1. **Branch**
   * Ensure you’re on the same branch in Nected that was updated in GitHub (e.g. `main`).
2. **Caching / refresh**
   * Try closing and reopening the Pull dialog, or refreshing the Git panel, then run Pull again.
3. **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:**

1. In the Pull flow, complete **Step 2 — Sync Integrations & Credentials**.
2. 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.
3. Retry the pull after all Integration/credential issues are resolved.

[Learn about the pull steps](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/pull-changes)

***

#### 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:**

| Option                          | Use when                                                                                                                    |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **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:**

| Status             | Meaning                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **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:**

1. During Pull, complete **Step 2 — Sync Integrations & Credentials** and **Step 3 — Update Missing Configs**.
2. In Nected, open **Integrations** and ensure every Integration referenced by the pulled logic exists and has valid credentials and config for this environment.
3. 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](https://docs.github.com) and your team’s branching policy.
* **Nected lifecycle:** See [Overview](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control) and [Commit & Push](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/commit-and-push).
* **Branches and PATs:** See [Branches](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/branches) and [Setup (GitHub)](https://docs.nected.ai/nected-docs/development-lifecycle/git-based-source-control/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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nected.ai/nected-docs/development-lifecycle/troubleshooting-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.