One of your commit messages is missing valid issue key
A Bitbucket, Jira, or custom Git hook can reject a push when the commit message does not contain a valid issue key such as PROJ-123. The safe fix is to inspect the accepted pattern, soft-reset the rejected commit, recommit with the right key, and push again.
TL;DR
- Cause: a repository hook is enforcing an issue-key format in commit messages.
- Fix: use
git reset --soft HEAD~1, then recommit with the correct key. - Do not use
git push --forcefor this error unless your team explicitly asks you to rewrite shared history. - Prevent repeats with a commit template or IDE commit-message check.
Source check – May 10, 2026: Git documents
commit-msghooks as a way to inspect or reject proposed commit messages, and push-time hooks such aspre-receivecan reject commits on the server. Atlassian’s Bitbucket documentation still describes linking commits to external services such as Jira by issue-key patterns.
| Topic | When | Command |
|---|---|---|
| Find the expected pattern | Before changing history | git log --oneline -5 |
| Undo only the rejected commit | Your changes should stay staged | git reset --soft HEAD~1 |
| Recommit with an issue key | After confirming the project key | git commit -m "PROJ-123: short message" |
Start here: If you just hit the error, jump to Step 2 – Soft Reset the Git Header; if you are setting policy for a team, read the IDE and prevention sections first.
How to Fix the “Commit Message Missing Valid Issue Key” Git Error
Encountering a [remote rejected] error message after a git push can stop your workflow in its tracks. If the message reads, “One of your commit messages is missing a valid issue key,” don’t worry. This is a common issue with a straightforward and safe solution.
This guide will walk you through why this error happens, the exact commands to fix it, and how to prevent it from happening again.
Enumerating objects: 17, done.
Counting objects: 100% (17/17), done.
Delta compression using up to 10 threads
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 865 bytes | 865.00 KiB/s, done.
Total 9 (delta 6), reused 0 (delta 0), pack-reused 0
remote:
remote: One of your commit messages is missing a valid issue key:
remote:
remote: cbfb6e6: feature/dhi-1490:added inbound rules
remote:
remote: For more information, see https://support.atlassian.com/bitbucket-cloud/docs/link-to-a-web-service/
To bitbucket.org:ShopDirect/ds-terraform-pbi-infrastructure.git
! [remote rejected] feature/dhi-1490-Add-RDP-Inbound -> feature/dhi-1490-Add-RDP-Inbound (pre-receive hook declined)
error: failed to push some refs to 'bitbucket.org:{MY_PRIVATE_REPO}/{MY_PRIVATE_REPO}infrastructure.git'Discrepancies in repo rules cause this error. You can see what your rules are by viewing your repository settings. I use Bitbucket so its in Repo > Settings > Repository Links
If you don’t have access to this part of the repo, the easiest thing to do is check previous commit logs to see how everyone else has written their commit message.
Understanding the Missing Valid Issue Key Error
This error typically arises when your Git repository is configured to enforce certain rules for commit messages. These rules often require linking commit messages to specific issue-tracking systems like Jira or Bitbucket Issues. If your commit message doesn’t adhere to these rules, the push is rejected.
Step 1 – View the Git Log.
View the previous git commits and look for the problem. My issue was that i had a rule that required the JIRA ticket to be in UPPER case, my initial commit was in lower case. I worked this out by reviewing other commit messages in the log.
git logFor Example:
commit bd2846e70c417d9de4e1dcca763ddbb85328b14d (HEAD -> feature/dhi-1490-Add-RDP-Inbound, origin/feature/dhi-1490-Add-RDP-Inbound)
Author: Richard Bailey <[email protected]k>
Date: Thu Sep 29 13:56:31 2022 +0100
feature/dhi-1490:added inbound rules
commit b48f4960a85dc24c840c00e822752917ebbe07b9 (origin/master, origin/HEAD, master)
Merge: a982cdc 378c1db
Author: Colleague 1 <[email protected]k>
Date: Wed Aug 3 10:13:57 2022 +0000
Merged in feature/DHI-1119 (pull request #55)
Feature/DHI-1119
Approved-by: Colleague3
Approved-by: Colleague4If you compare the above you will see that my commit bd2846e70c417d9de4e1dcca763ddbb85328b14d was written in lower case, but commit b48f4960a85dc24c840c00e822752917ebbe07b9 was in upper.
Step 2 – Soft Reset the Git Header.
git reset --soft HEAD~1 Step 3 – Proceed to Recommit Your Work
git add .
commit -a -m'Feature/DHI-1490-my-commit-message'
git pushThe code should now commit.
Example (Bitbucket)
In Bitbucket, if you have a rule requiring JIRA issue keys in uppercase, a commit message like feature/dhi-1490:added inbound rules would fail. You’d need to amend it to Feature/DHI-1490: Added inbound rules (capitalized “DHI”).
Important Note:
Avoid force pushing (git push -f) unless absolutely necessary, as it can overwrite others’ work and disrupt collaboration.
Additional Tips:
- Configure your code editor or IDE to automatically insert the correct issue key format in commit messages.
- If the issue persists, consult your repository administrator or the documentation of your Git hosting platform.
Here’s how you can configure WebStorm and VS Code to automatically insert issue key formats in your commit messages:
WebStorm: Missing Valid Issue Key
- Install the Jira Plugin:
- Go to File > Settings > Plugins.
- Search for “Jira” and install the official JetBrains Jira plugin.
- Restart WebStorm.
- Link Your Jira Account:
- In the Tools menu, you should now see a Tasks & Contexts option.
- Click on it and select Open Task.
- Follow the prompts to connect your Jira account.
- Configure Commit Message Template:
- Go to File > Settings > Version Control > Commit Dialog.
- In the “Commit Message” section, you can customize the template:
- Use
{task}to automatically insert the Jira issue key. - Add any other relevant text, like “Fixes” or “Implements.”
- Use
Example Template:
{task} - {summary}Now, when you commit in WebStorm, the plugin will automatically insert the linked Jira issue key and summary into your commit message.
VS Code: Missing Valid Issue Key
- Install an Extension:
- Several extensions offer commit message templates. Here are a few popular options:
- Git Commit Template
- Commit Message Editor
- Conventional Commits
- Several extensions offer commit message templates. Here are a few popular options:
- Configure the Template:
- After installing your chosen extension, go to File > Preferences > Settings.
- Search for the extension’s settings.
- Look for a setting like “Template” or “Format” and customize it to your liking.
Example Template:
[<ISSUE_KEY>] - <Short description of changes>Now, when you commit in VS Code, you can use the extension’s command or shortcut to insert the template, prompting you to enter the issue key and description.
General Tips:
- Consistency is Key: Ensure your team agrees on a standard format for issuing keys and committing messages.
- Customization: Adapt the templates to match your project’s specific workflow and requirements.
- Branch Naming: For even clearer tracking, consider using branch names that include the issue key (e.g., “feature/DHI-1490”).
Check out more Tech Quickys here.
Frequently Asked Questions (FAQ)
Q1: What does git reset --soft HEAD~1 actually do?
This command tells Git to move the HEAD pointer back by one commit. The --soft flag ensures that the changes in that undone commit are kept in your staging area. This is different from a --hard reset, which would discard your changes entirely. For more complex situations, you may need to learn about [Internal Link: advanced Git reset commands].
Q2: Is it safe to use git push --force to fix this?
No. You should avoid using git push --force to solve this problem. A force push overwrites the remote branch’s history. While it might seem like a quick fix, it will not bypass the server-side hook causing the error. The push will still be rejected, and force pushing can cause serious problems for your collaborators by erasing their work.
Thanks for taking the time to read this article. if you have any questions or feedback, please write in the comment section below.
Leave a Reply