Cannot identify main workflow YAML in directory. Expected '$

Error message

Cannot identify main workflow YAML in directory. Expected '${slug}.yaml' or a single .yaml file.

What it means

For directory-sourced marketplace entries, the installer must pick one main YAML file from the downloaded listing: prefer `<slug>.yaml`, else the sole `.yaml` file. If neither rule resolves a candidate — multiple YAML files and none named after the slug — the command cannot decide which is the workflow entrypoint and aborts.

Source

Thrown at packages/cli/src/commands/workflow.ts:5225

  entry: MarketplaceEntryJson,
  slug: string,
  archonDir: string,
  force: boolean | undefined,
  existsSync: (p: string) => boolean,
  mkdirSync: (p: string, opts: { recursive: boolean }) => void,
  writeFileSync: (p: string, data: string) => void
): Promise<void> {
  const { owner, repo, path } = parseGitHubUrl(entry.sourceUrl);
  const items = await fetchGitHubDirectory(owner, repo, path, entry.sha);

  // Identify the main workflow YAML (named <slug>.yaml or the only .yaml in root)
  const yamlFiles = items.filter(f => f.type === 'file' && f.name.endsWith('.yaml'));
  const mainYaml =
    yamlFiles.find(f => f.name === `${slug}.yaml`) ??
    (yamlFiles.length === 1 ? yamlFiles[0] : undefined);

  if (!mainYaml) {
    throw new Error(
      `Cannot identify main workflow YAML in directory. Expected '${slug}.yaml' or a single .yaml file.`
    );
  }

  const workflowsDir = join(archonDir, 'workflows');
  const destWorkflow = join(workflowsDir, `${slug}.yaml`);

  if (existsSync(destWorkflow) && !force) {
    throw new Error(
      `Workflow '${slug}' already exists at ${destWorkflow}.\nUse --force to overwrite.`
    );
  }

  // Install the main workflow YAML
  const mainContent = await downloadRawFile(owner, repo, mainYaml.path, entry.sha);
  mkdirSync(workflowsDir, { recursive: true });
  writeFileSync(destWorkflow, mainContent);
  console.log(`  Workflow: ${destWorkflow}`);

View on GitHub (pinned to 0773b97458)

Solutions

Name the primary workflow `<slug>.yaml` inside the source directory, or leave exactly one `.yaml` file
Remove or move helper YAMLs into a subdirectory so only one remains
If the repo uses `.yml`, rename to `.yaml` (the installer only filters `.yaml`)
Update the marketplace entry's path to point at a directory following the convention

Example fix

// before
repo/workflows-my-pack/{review.yaml, lint.yaml}   // slug: my-pack → ambiguous
// after
repo/workflows-my-pack/my-pack.yaml   // matches '<slug>.yaml'
repo/workflows-my-pack/steps/lint.yaml // supporting files out of the way

Defensive patterns

Strategy: validation

Validate before calling

const yamls = items.filter(f => f.type === 'file' && f.name.endsWith('.yaml'));
const main = yamls.find(f => f.name === `${slug}.yaml`) ?? (yamls.length === 1 ? yamls[0] : null);
if (!main) throw new Error(`No unambiguous main YAML for '${slug}' (candidates: ${yamls.map(f=>f.name).join(', ')})`);

Type guard

function hasUnambiguousMainYaml(items: GitHubContentItem[], slug: string): boolean {
  const yamls = items.filter(f => f.type === 'file' && f.name.endsWith('.yaml'));
  return yamls.some(f => f.name === `${slug}.yaml`) || yamls.length === 1;
}

Try / catch

try {
  await workflowInstallCommand(slug);
} catch (e) {
  if (e instanceof Error && e.message.includes('Cannot identify main workflow YAML')) {
    // restructure the source directory per the <slug>.yaml convention
  } else throw e;
}

Prevention

Publish marketplace directories with a `<slug>.yaml` entrypoint
Keep auxiliary YAMLs in subdirectories or non-.yaml extensions
Use `.yaml` (not `.yml`) for workflow files in marketplace repos
Rename entries when slugs change so `<slug>.yaml` keeps matching

When it happens

Trigger: `installFromDirectory` filters the GitHub contents listing to `.yaml` files, then finds neither `f.name === '${slug}.yaml'` nor exactly one candidate: directory has multiple YAMLs with different names, or zero YAML files (only `.yml` or other assets).

Common situations: Marketplace directory contains several workflow YAMLs without a `<slug>.yaml` (e.g. `lint.yaml`, `review.yaml`); repo uses `.yml` extension which the filter does not accept; slug renamed so `<slug>.yaml` no longer matches; directory only holds supporting files.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/69d7928b9680ecb6. Report an issue: GitHub.