theonedev/onedev · error · ExplicitException

Spec not found in workspace project hierarchy

Error message

Spec not found in workspace project hierarchy

What it means

Thrown by DefaultWorkspaceService.run() when a workspace's rendered spec is null. OneDev resolves a workspace's CI/CD spec by walking up the project hierarchy (project, then parents) to find the closest spec defining a workspace; if no project in the chain provides one, execution cannot proceed. It is an ExplicitException, so it is surfaced verbatim to the user as an expected, explainable failure.

Source

Thrown at server-core/src/main/java/io/onedev/server/workspace/DefaultWorkspaceService.java:778

			if (spec.isRunInContainer()) {
				throw new ExplicitException("""
					No applicable provisioner discovered for current workspace. \
					Please check if docker is installed on OneDev server, or configure \
					a kubernetes provisioner if you would like workspaces to run as pods""");
			} else {
				throw new ExplicitException("""
					No applicable provisioner discovered for current workspace. \
					Please add a shell provisioner in menu 'Administration / Workspace Provisioners'""");
			}
		}
	}

	private Future<Void> run(Workspace workspace) {
		Workspace.push(workspace);
		try {
			var spec = workspace.getSpec();
			if (spec == null)
				throw new ExplicitException("Spec not found in workspace project hierarchy");

			var interpolator = new WorkspaceVariableInterpolator(workspace);
			spec = interpolator.interpolateProperties(spec);

			String token = workspace.getToken();
			var project = workspace.getProject();
			var projectId = project.getId();
			var projectPath = project.getPath();
			var projectGitDir = projectService.getGitDir(project.getId()).getAbsolutePath();
			var workspaceId = workspace.getId();
			var workspaceNumber = workspace.getNumber();

			var workspaceLogger = logService.newLogger(workspace.getLoggingSupport());
			var provisioner = getProvisioner(workspace, spec, workspaceLogger);

			var gitEmail = workspace.getUser().getGitEmailAddress();
			
			String cloneUrl;

View on GitHub (pinned to d44925c47c)

Solutions

1. Add a workspace spec (.onedev-workspace.yml) to the project (or an ancestor project) that owns the workspace.
2. Commit the spec file to the branch/ref the job runs against.
3. Fix the project hierarchy so a parent project actually defines the workspace spec.
4. Verify the job's project is the intended one — the spec may exist in another repository.

Example fix

// before: job runs in project with no workspace spec -> exception
// after: add .onedev-workspace.yml at repo root
type: command
tasks:
- name: setup
  commands: |
    ./setup-dev-env.sh

// Java
if (workspace.getSpec() == null)
    throw new ExplicitException("Project hierarchy has no workspace spec; add .onedev-workspace.yml");

try { runWorkspace(workspace); } catch (ExplicitException e) { log.error("No workspace spec: {}", e.getMessage()); }

When it happens

Trigger: A job/step requires running a workspace (Workspace.push(workspace) then spec execution), but neither the workspace's own project nor any ancestor project has a workspace spec (.onedev-workspace.yml or spec property) attached.

Common situations: Kicking off a job that expects a workspace while the repository has no .onedev-workspace.yml; the spec lives only in a sibling branch or was deleted/renamed; spec resolution disabled on the project so hierarchy lookup returns nothing; typo in spec file location.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• I need to create workspace to do the job, but no applicable
• Build spec not defined (import project: {0}, import revision
• Project not found: ${projectPath}
• Invalid access token
• Not authorized

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