ramensoftware/windhawk · error

Mod id must be specified in the source code

Error message

Mod id must be specified in the source code

What it means

When installing a mod from source, the panel extracts the mod's metadata (which includes the `id` from the source's metadata block) and requires it to be present before installMod is called. A mod source without an `#pragma`-style id / metadata id cannot be identified in storage, so the operation aborts.

Solutions

1. Add the `id` field to the mod's metadata block in the source (e.g. `// ==WindhawkMod== ... ** id=... `)
2. Re-download the complete mod source including its metadata header
3. Fix whatever preprocessing stripped the metadata before extraction

Example fix

// before
// ==WindhawkMod==
// ==/WindhawkMod==
// after
// ==WindhawkMod==
// ... ==/WindhawkMod==
/*
[Metadata]
id=my.mod.id
*/

const meta = parseModMetadata(modSource);
if (!meta?.id) {
  alert('Mod source is missing the required id metadata field.');
  return;
}

const hasId = (m: { id?: string } | null): m is { id: string } => typeof m?.id === 'string' && m.id.length > 0;

try { await panel.installMod(data); } catch (e) { if (e.message === 'Mod id must be specified in the source code') notifyMissingId(); else throw e; }

When it happens

Trigger: WindhawkPanel handles an install message where data.modSource's extracted metadata has no id — e.g. installing from a hand-written or pasted source file missing the id field.

Common situations: Author creates a new mod and forgets the id line in the metadata block; a tool strips metadata comments; pasting only the code portion of a mod.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Mod id specified in the source code doesn't match
• Failed to parse mod metadata
• Missing settings key
• Initial settings arrays must contain at least one template…
• Invalid object array schema definition.

AI-assisted analysis of ramensoftware/windhawk@61d99ed8e1 (2026-09-12). Data as JSON: /api/errors/f95a676285732e04. Report an issue: GitHub.

Appendix: source

Thrown at src/windhawk-vscode/src/extension.ts:832

				succeeded
			});
		},
		installMod: async message => {
			const data: InstallModData = message.data;

			let installedModDetails: InstallModReplyData['installedModDetails'] = null;
			let readBackError: WireError | undefined;

			try {
				windhawkCompilerOutput?.clear();
				windhawkCompilerOutput?.hide();

				const modId = data.modId;
				const modSource = data.modSource;

				const metadata = await extractMetadataOrThrow(this._utils.core, modSource, this._language);
				if (!metadata.id) {
					throw new Error('Mod id must be specified in the source code');
				} else if (metadata.id !== modId) {
					throw new Error('Mod id specified in the source code doesn\'t match');
				}

				const op = this._utils.core.installMod({
					storageId: modId,
					source: modSource,
					metadata,
					disabled: data.disabled,
					loggingEnabled: data.loggingEnabled,
					compileLocally: this._alwaysCompileModsLocally,
					trackInProfile: true,
				});

				// Track the operation for the duration of the install so
				// cancelInstallMod can find it, and drop it however it settles -
				// a completion, a failure, or the cancel itself.
				this._currentInstallOps.set(modId, op);

View on GitHub (pinned to 61d99ed8e1)