Troubleshooting Guide
This guide covers the errors Koodisi reports when a Git operation fails, what causes each one, and how to fix it. Koodisi uses Isomorphic Git, which runs in your browser against the local datastore, so several of these errors are about local state rather than the remote repository.
Export the local datastore before any recovery step that clears or re-clones, especially when your latest commits are not pushed. See Managing the Local Datastore.
Credential errors
An expired or wrong credential is the most common cause of a failed remote operation. Koodisi reports the HTTP status behind the failure, which tells you which problem you have.
| Message | Cause | What to do |
|---|---|---|
The saved Git credential may be invalid or expired. Update it in Git Settings and retry the remote operation. | The token is expired or wrong. | Generate a new personal access token in your Git provider, then update the saved credential. |
Push Failed, Please verify Git credentials and retry | The push was rejected as unauthorized. Koodisi opens the credentials dialog for you. | Update the credential in the dialog and retry the push. |
The credential does not have permission for this repository or operation. | The credential is valid but lacks the scope or repository access. | Grant the token access to the repository, or use a credential that has it. |
Verify the repository URL and the credential's repository access. | The repository was not found — a wrong URL, or a token that cannot see it. | Check the remote URL, then check the token's repository access. |
To update a credential, select the Credentials icon in the Version Control panel header, or go to Settings > Git Settings > Credential Manager. See Managing Credentials.
Push errors
| Message | Cause | What to do |
|---|---|---|
Pushes to this branch are not permitted; you must use a pull request to update this branch. | The branch is protected in your Git provider. | This is the protection working as intended. Push to a feature branch and raise a pull request. See Merging and Pull Requests. |
Push rejected because it was not a simple fast-forward. | The remote branch moved ahead of your local branch after you committed. | Use the committed-work recovery path in Handling Merge Conflicts. |
Merges with conflicts are not supported yet. | Pull found remote changes that conflict with your local commits. | Resolve in your Git provider. See Handling Merge Conflicts. |
No staged files present to commit. | Nothing is staged. | Stage your changes on the Changes tab first. |
Please enter a commit Message | The commit message is empty. | Enter a message, or accept the one Koodisi generates from your staged files. |
Local repository errors
Cannot find HEAD
Git was not initialized properly for the application, the Git metadata is corrupted, or the repository setup is incomplete.
Koodisi offers Cannot find HEAD — Please clear your local data store and re-clone the application. with Open Local Data Store.
- Select Open Local Data Store, then Export datastore to take a backup — essential if your latest commits are not pushed.
- Select Clear Datastore and confirm.
- Re-clone the application from the remote repository. See Cloning Git Applications.
- If the re-clone is missing recent local changes, import the export you took.
Initial commit is needed to create the master branch
The repository has no commits yet, so there is no branch to work from. Stage your application content on the Changes tab and commit it. That first commit creates the branch.
Application missing from local storage
The application is not in this browser's datastore — a different browser or machine, or a cleared datastore.
If you have already pushed the application to a remote repository, select Clone My Application in the Version Control panel to bring it back down.
Application missing from active branch
The application exists locally, but not on the branch you have checked out. This happens in a multi-module repository where an application lives on some branches and not others.
Select a branch that contains the application from the Active branch list, under Local Branches or Remote Branches.
Unable to verify local application storage
The local application status could not be checked, so Koodisi will not guess. Select Retry status check before cloning or running further Git operations.
Clone errors
| Symptom | Cause | What to do |
|---|---|---|
| The clone fails | An invalid repository URL or credentials, or a corrupted local datastore. | Verify the remote URL, revalidate the credential or token, clear the datastore, then clone again. |
The repository contains application content. Use Clone from Git instead. | You are creating a new application against a repository that already holds content. | Use Clone from Git to bring the existing application in. |
Repository already has history, including README-only repositories. Use Clone from Git to preserve it. | The repository has commits — a readme is enough. | Clone rather than create, or create the application in an empty repository. |
The repository README conflicts with this application's documentation. Use an empty repository or Clone from Git as a new application. | The repository's readme collides with the application's own documentation file. | Use an empty repository, or clone as a new application. |
Application cloned, but workflow validation failed. | The clone succeeded; the cloned workflows have validation errors. | The application is present. Open the workflows and fix the reported errors. |
Bundle applications can't be used with Git | The application type is a bundle. | Git control is available for orchestration applications. |
Panel and visibility problems
| Symptom | Cause | What to do |
|---|---|---|
| The Version Control icon is missing | The application is not Git-enabled, or the selected tree node does not offer the panel. | Select an application, folder, workflow, resource, or schema node. For a non-Git application, see Add Git to an Existing Application. |
| The Branch Type list is missing when creating a branch | Branch naming patterns are turned off for your organization, or none are defined. | Enter any valid branch name, or ask an administrator to enable the policy. See Git Branching Policy. |
| Deleted remote branches still appear under Remote | Remote-tracking references have not been refreshed. | Select More > Fetch & Prune. |
| You cannot switch branches | The current branch has uncommitted changes. | Commit, stash, or discard first. See Using Git with Applications. |
| A schema behaves differently across branches | An edited schema is tracked in the branch that edited it; other branches still use the reference. | Merge the schema change to the target branch, then pull in the dependent branches. See Schema Guidelines. |
Choosing between cloning and creating
- Clone when a repository and branch already exist with commits you need to work on.
- Create a new application when no repository exists yet, or you are starting from scratch in an empty repository.
Working on a branch other than the default
To start work on a specific branch of an existing repository:
- Export the local datastore as a backup.
- Clone the application from the repository. See Cloning Git Applications.
- Select Fetch to retrieve all branches.
- On the Branches tab, check out the branch you want under Remote.
Related topics
- Managing the Local Datastore — export, import, and clear
- Handling Merge Conflicts — conflicting pulls and rejected pushes
- Working with Git Applications: Best Practices — avoiding these errors