laurent22/joplin · error · Error

Remote HEAD is empty. Make sure you have pushed your changes

Error message

Remote HEAD is empty. Make sure you have pushed your changes.

What it means

Thrown by verifyGitState when `git ls-remote origin <branch>` returns an empty string, meaning the remote has no ref matching the current local branch. This happens when the local branch has never been pushed, the remote branch name differs, or the remote is empty. The earlier runGit call succeeded (no error) but produced no stdout.

Source

Thrown at packages/generator-joplin/generators/app/templates/script/publish/steps/verifyGitState.ts:49

	// Gets the current latest local commit hash
	const commitHash = await runGit('git rev-parse HEAD', 'Could not get commit hash. Ensure you are in a valid Git repository with at least one commit.');
	if (commitHash.length !== 40) {
		throw new Error('Failed to extract a valid commit hash. Ensure that git is properly initialized and you have made at least one local commit (git commit) before publishing.');
	}
	logger.success(`Commit hash extracted: ${commitHash}`);

	// check if the local project is linked to github
	await runGit('git remote get-url origin', 'No remote named \'origin\' found. Make sure your plugin repository is hosted on GitHub.');

	const currentBranch = await runGit('git rev-parse --abbrev-ref HEAD', 'Failed to retrieve current branch name. Ensure git is configured correctly.');
	if (currentBranch === 'HEAD') {
		throw new Error('You are in a detached HEAD state. Checkout a branch (e.g. git checkout main) and push before publishing.');
	}

	const remoteHeadLine = await runGit(`git ls-remote origin ${currentBranch}`, 'Could not retrieve remote HEAD. Make sure you have pushed your changes and have an internet connection.');
	if (!remoteHeadLine) {
		throw new Error('Remote HEAD is empty. Make sure you have pushed your changes.');
	}

	const parts = remoteHeadLine.split('\n')[0].split(/\s+/);
	if (parts.length < 2) {
		throw new Error(`Unexpected git ls-remote output: "${remoteHeadLine}". Make sure your git remote and branch are configured correctly.`);
	}

	const remoteHash = parts[0];
	if (remoteHash.length !== 40) {
		throw new Error('Failed to extract a valid remote commit hash.');
	}

	if (remoteHash !== commitHash) {
		throw new Error('Your local commit has not been pushed to GitHub. Run git push then try publishing again.');
	}
	logger.success('Local commit is synced with remote.');

	return commitHash;

View on GitHub (pinned to 2654b33620)

Solutions

1. Push the branch: git push -u origin <current-branch>.
2. Confirm the remote has the branch: git ls-remote --heads origin.
3. If the remote branch name differs, rename locally or push to the matching remote branch.

Example fix

# before
git commit -m 'feat: x'
 npm run publish
# after
git push -u origin main
 npm run publish

const remote = execSync(`git ls-remote origin ${branch}`, { encoding: 'utf8' }).trim();
if (!remote) {
  throw new Error('Remote has no such branch. Run: git push -u origin ' + branch);
}

function hasRemoteRef(out) { return out.trim().length > 0; }

When it happens

Trigger: Local branch was never pushed to origin; the remote branch was deleted; branch name case mismatch between local and remote; the remote 'origin' points to an empty repo; network returned empty despite exit 0 (rare).

Common situations: Developer committed locally and ran publish without pushing; the remote branch was renamed/deleted by a collaborator; first publish of a new plugin repo with no remote commits yet.

Related errors

• Unexpected git ls-remote output: "${remoteHeadLine}". Make s
• Failed to extract a valid remote commit hash.
• Your local commit has not been pushed to GitHub. Run git pus
• Failed to extract a valid commit hash. Ensure that git is pr
• You are in a detached HEAD state. Checkout a branch (e.g. gi

AI-assisted analysis of laurent22/joplin@2654b33620 (2026-08-12). Data as JSON: /api/errors/b080dc8fc2e51fcd. Report an issue: GitHub.