theonedev/onedev · error · ExplicitException

I need to create workspace to do the job, but no applicable

Error message

I need to create workspace to do the job, but no applicable workspace spec found

What it means

Thrown by DefaultWorkspaceService when a job requires a workspace but no workspace spec in the project hierarchy matches the job's criteria (no applicable spec found among candidate projects/branches). It is an ExplicitException with a user-friendly message, indicating a configuration gap rather than an internal bug.

Source

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

									}
								});		
								return true;
							} else if (workspace.getStatus() == Workspace.Status.INACTIVE) {
								sessionService.run(() -> {
									taskFailedCallback.onTaskFailed(workspaceReference);
								});
								return true;
							} else {
								return false;
							}
						})) {
							break;
						}
					}
				});
			});
		} else {
			throw new ExplicitException("I need to create workspace to do the job, but no applicable workspace spec found");
		}
	}

	private ClusterTask<Void> newRunWorkspaceTask(WorkspaceContext context) {
		return new ClusterTask<Void>() {
		
			private void run(WorkspaceContext context, TaskLogger workspaceLogger) {
				var workspaceId = context.getWorkspaceId();
				transactionService.run(() -> {
					var workspace = load(workspaceId);
					if (!Objects.equals(workspace.getProvisionerName(), context.getProvisioner().getName())) {
						workspace.setProvisionerName(context.getProvisioner().getName());
						update(workspace);
					}
				});
	
				var runtime = context.getProvisioner().provision(context, workspaceLogger);
				workspaceRuntimes.put(workspaceId, runtime);

View on GitHub (pinned to d44925c47c)

Solutions

1. Add a workspace spec applicable to the job's project and branch.
2. Widen the spec's applicability (remove restrictive branch/path conditions).
3. Change the job configuration to not require a workspace (use a different executor).
4. Verify the job runs in a project whose hierarchy includes a spec-defining project.

Example fix

// before: no spec on feature branches -> exception
// after: add .onedev-workspace.yml (or job spec) covering the branch
type: command
tasks:
- name: dev
  commands: |
    ./setup.sh

// Java
boolean hasSpec = projectHierarchyStream()
    .anyMatch(p -> p.getWorkspaceSpec() != null);
if (!hasSpec)
    throw new ExplicitException("Add a workspace spec before queueing workspace-dependent jobs");

try { runJobWithWorkspace(job); } catch (ExplicitException e) { if (e.getMessage().contains("no applicable workspace spec")) promptUserToDefineSpec(); }

When it happens

Trigger: A CI/CD job declares it needs a workspace (e.g. runs on a dev container/workspace-based executor) but no candidate spec in the hierarchy qualifies — specs exist but none is applicable to this job/branch, or none exists at all.

Common situations: Branch protection/CI setup requires workspaces but only some branches define the spec; spec criteria (image, setup commands) filtered out all candidates; job moved to a project whose ancestors lack workspace specs.

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

• Spec not found in workspace project hierarchy
• 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/224449c0930598f5. Report an issue: GitHub.