theonedev/onedev · error · ExplicitException

Loopback address not allowed for target docker image of push

Error message

Loopback address not allowed for target docker image of push image step, please use ip address or host name instead

What it means

PushImageStep builds a 'crane push' command for publishing a docker image. Loopback addresses (localhost, 127.0.0.1) are rejected in destImage because the push runs inside the job container, where loopback would not point at the intended registry host. Any destImage containing those strings throws this ExplicitException.

Source

Thrown at server-core/src/main/java/io/onedev/server/buildspec/step/PushImageStep.java:78

	public String getMoreOptions() {
		return moreOptions;
	}

	public void setMoreOptions(String moreOptions) {
		this.moreOptions = moreOptions;
	}

	static List<InputSuggestion> suggestVariables(String matchWith) {
		return BuildSpec.suggestVariables(matchWith, true, true, false);
	}

	@Override
	public String getCommand() {
		var builder = new StringBuilder("crane push");
		if (getMoreOptions() != null)
			builder.append(" ").append(getMoreOptions());			
		if (getDestImage().contains("localhost") || getDestImage().contains("127.0.0.1"))
			throw new ExplicitException("Loopback address not allowed for target docker image of push image step, please use ip address or host name instead");
		builder.append(" /onedev-build/work/").append(getSrcPath()).append(" ").append(getDestImage());
		return builder.toString();
	}
	
}

View on GitHub (pinned to d44925c47c)

Solutions

1. Replace 'localhost' in destImage with the registry host's IP address or DNS/host name reachable from the job executor.
2. Use the registry service name (e.g. registry.onedev-cluster.svc) or its cluster IP instead of loopback.
3. Rename any registry host whose name merely contains 'localhost' or '127.0.0.1' since the check is substring-based.

Example fix

// before
- type: PushImage
  destImage: localhost:5000/myapp:1.0
// after
- type: PushImage
  destImage: registry.mycompany.internal:5000/myapp:1.0

// Validate destImage in spec review or pre-step script
if (destImage.contains("localhost") || destImage.contains("127.0.0.1")) {
    throw new IllegalArgumentException("destImage must use a registry host name or IP, not loopback: " + destImage);
}

When it happens

Trigger: Configuring a PushImageStep whose destImage contains 'localhost' or '127.0.0.1' (substring check, so even 'my-localhost-registry:5000' triggers it).

Common situations: Copying a docker push config from local testing where localhost pointed at a local registry; intending an in-cluster registry but writing localhost instead of the registry service DNS name or pod IP.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• This build is not authorized to sync to project:
• Step template not found:
• Error validating build spec (project: %s, commit: %s, locati
• Build spec not defined (project: %s, commit: %s)
• This workspace can only be provisioned by docker provisioner

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/92d12327bd40caa3. Report an issue: GitHub.