MagicMirrorOrg/MagicMirror · warning

Module ${index} ("${mod.module}") uses unknown position: "${

Error message

Module ${index} ("${mod.module}") uses unknown position: "${mod.position}"

What it means

validateModulePositions verifies that each module entry's optional `position` matches a known region name (positionList). If a position is set but isn't one of the valid region strings, this warning prints the module index, name, and bad value; validation continues and the module will simply not be displayed in any region.

Source

Thrown at js/utils.js:276

			Log.error(`This module configuration contains errors:\n${JSON.stringify(mod, null, 2)}\nmodule entry must be an object`);
			throw new ConfigError("");
		}

		// `module` (the module name) is required and must be a string
		if (typeof mod.module !== "string") {
			Log.error(`This module configuration contains errors:\n${JSON.stringify(mod, null, 2)}\nmodule: must be a string`);
			throw new ConfigError("");
		}

		// `position` is optional, but must be a string when provided
		if (mod.position !== undefined && typeof mod.position !== "string") {
			Log.error(`This module configuration contains errors:\n${JSON.stringify(mod, null, 2)}\nposition: must be a string`);
			throw new ConfigError("");
		}

		// `position` is optional, but when set it must match a known region
		if (mod.position && !positionList.includes(mod.position)) {
			Log.warn(`Module ${index} ("${mod.module}") uses unknown position: "${mod.position}"`);
			Log.warn(`Known positions are: ${positionList.join(", ")}`);
		}
	}

	Log.info(styleText("green", "Your modules structure configuration doesn't contain errors :)"));
};

module.exports = { loadConfig, getModulePositions, moduleHasValidPosition, getAvailableModulePositions, checkConfigFile, ConfigError };

View on GitHub (pinned to 4b4a59534f)

Solutions

1. Change position to one of the known values listed in the companion 'Known positions are:' warning.
2. Use exact lowercase snake_case: top_bar, top_left, top_center, top_right, upper_third, upper_left/center/right, middle_left/center/right, lower_left/center/right, bottom_bar, bottom_left, bottom_center, bottom_right, fullscreen_above, fullscreen_below.
3. Remove position entirely if the module doesn't need to be displayed.

Example fix

// before
{ module: "clock", position: "Top_Left" }
// after
{ module: "clock", position: "top_left" }

// validate positions before starting:
const valid = ["top_bar","top_left","top_center","top_right","upper_third","upper_left","upper_center","upper_right","middle_left","middle_center","middle_right","lower_third","lower_left","lower_center","lower_right","bottom_left","bottom_center","bottom_right","bottom_bar","fullscreen_above","fullscreen_below"];
for (const m of config.modules) {
  if (m.position && !valid.includes(m.position)) throw new Error(`${m.module}: bad position ${m.position}`);
}

When it happens

Trigger: A module config sets position to an unrecognized string like "top", "bottom_left", "Top_Left" (wrong case), or a made-up region.

Common situations: Typos in region names; copying positions from other dashboard frameworks; capitalization mistakes (positions are lowercase snake_case like upper_third, top_left, bottom_bar).

Related errors

• Latitude and longitude are required
• siteCode and provCode are required
• Unknown weather type: ${this.config.type}
• Latitude and longitude are required
• Known positions are: ${positionList.join(", ")}

AI-assisted analysis of MagicMirrorOrg/MagicMirror@4b4a59534f (2026-08-31). Data as JSON: /api/errors/9e1d2ceca5e60cfa. Report an issue: GitHub.