{"record":{"id":"b46f122459c8221f","repo":"squidfunk/mkdocs-material","slug":"error-reading-layout-file-path-in-base-e","errorCode":null,"errorMessage":"Error reading layout file '{path}' in '{base}':\n{e}","messagePattern":"Error reading layout file '(.+?)' in '(.+?)':\n(.+?)","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/social/plugin.py","lineNumber":765,"sourceCode":"        ]:\n            path = os.path.join(base, f\"{name}.yml\")\n            path = os.path.normpath(path)\n\n            # Skip if layout does not exist and try next directory\n            if not os.path.isfile(path):\n                continue\n\n            # Open file and parse as YAML\n            with open(path, encoding = \"utf-8-sig\") as f:\n                layout: Layout = Layout(config_file_path = path)\n                try:\n                    layout.load_dict(yaml.load(f, SafeLoader) or {})\n\n                # The layout could not be loaded because of a syntax error,\n                # which we display to the author with a nice error message\n                except Exception as e:\n                    path = os.path.relpath(path, base)\n                    raise PluginError(\n                        f\"Error reading layout file '{path}' in '{base}':\\n\"\n                        f\"{e}\"\n                    )\n\n                # Validate layout and abort if errors occurred\n                errors, warnings = layout.validate()\n                for _, w in warnings:\n                    log.warning(w)\n                for _, e in errors:\n                    path = os.path.relpath(path, base)\n                    raise PluginError(\n                        f\"Error reading layout file '{path}' in '{base}':\\n\"\n                        f\"{e}\"\n                    )\n\n                # Store layout and variables\n                self.card_layouts[name] = layout\n                self.card_variables[name] = []","sourceCodeStart":747,"sourceCodeEnd":783,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/social/plugin.py#L747-L783","documentation":"Social card layouts can be customized via YAML layout files. When _resolve_layout attempts to load such a file and the YAML cannot be parsed (any exception during open/parse/load_dict), the plugin wraps the original exception message into a PluginError showing the relative path and base directory, so syntax mistakes in the custom layout are surfaced clearly to the author.","triggerScenarios":"on_page_markdown, on_post_page or _generate resolves a card layout defined in a .yml file whose content raises during yaml.load(..., SafeLoader) or layout.load_dict — e.g. bad indentation, tabs, wrong types, or unparseable YAML.","commonSituations":"Copy-pasting a custom layout with wrong indentation or tabs; using YAML features unsafe for SafeLoader; invalid data types for layout options (string where size/int expected); an empty or truncated layout file.","solutions":["Look at the '{e}' message in the error for the exact YAML problem and fix the syntax (indentation, tabs, quoting) at that line","Validate the file with a YAML parser: python -c 'import yaml;print(yaml.safe_load(open(\"layout.yml\")))'","Compare against a working upstream layout file and adjust keys/types to match the expected schema"],"exampleFix":"# before (tabs break YAML)\noptions:\n\tbackground_color: '#000'\n# after\noptions:\n  background_color: '#000000'","handlingStrategy":"validation","validationCode":"import yaml, sys\ntry:\n    data = yaml.safe_load(open(\"custom-layout.yml\"))\nexcept yaml.YAMLError as e:\n    sys.exit(f\"Invalid layout YAML: {e}\")","typeGuard":null,"tryCatchPattern":"try:\n    mkdocs build\nexcept SystemExit:\n    # message contains the YAML exception; fix the indicated line\n    pass","preventionTips":["Use spaces, never tabs, in layout YAML files","Validate custom layouts with a YAML parser in pre-commit","Copy from an upstream example layout and change values, not structure"],"tags":["yaml","social-plugin","mkdocs","syntax-error","layout"],"backgroundTag":"yaml-syntax-error","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}