How to Fix “Property Is Not Allowed” .yaml-schema Error

Published On - August 19, 2025

Sophia Willson blog

YAML schemas are a powerful way to validate your configuration files and ensure they follow the necessary rules and structure. However, when tinkering with YAML-based configurations—such as in CI/CD pipelines with GitHub Actions, Kubernetes configurations, or VS Code settings—you may sometimes encounter the dreaded “Property is not allowed” warning. This can be frustrating, especially when your intention seems perfectly valid. Fortunately, fixing this error is usually straightforward once you understand the root of the problem.

Let’s dive into what causes this error and how you can resolve it effectively.

What Does “Property Is Not Allowed” Mean?

This error typically surfaces when a YAML schema expects a certain structure or set of predefined properties, and your file includes a property that is not defined or allowed by that schema. In other words, your configuration includes an unexpected or incorrect key.

Most often, this occurs in environments where a schema is used to provide IntelliSense, validation, or code completion—such as Visual Studio Code with YAML schema support, or automated tools that process YAML files for deployment.

Common Scenarios Where the Error Appears

Several common platforms where users often experience this error include:

  • GitHub Actions: Misplacing or misnaming steps or keys in the workflow file.
  • Kubernetes: Defining keys or properties not supported by the Kubernetes API for a particular resource.
  • Docker Compose: Typo in service configurations or use of outdated properties.
  • OpenAPI or Swagger: Adding unsupported fields in specs.

Let’s look at how to resolve the issue with a practical step-by-step approach.

How to Fix the Error

  1. Understand the Schema You’re Working With
    First and foremost, identify what schema your YAML file is expected to follow. Schemas are sometimes provided explicitly via a $schema tag or inferred by tools like VS Code depending on the file name or context.
    For example, in GitHub Actions, the schema is defined by the structure required in .github/workflows/*.yml files. Reading the official documentation often helps clarify required and optional fields.
  2. Check for Typos or Misspelled Properties
    A very common cause is a simple typo. For instance, writing enviroment instead of environment will break validation. Use a YAML-aware editor with schema validation enabled to highlight such issues immediately.
  3. Use a Schema Validator
    Several online tools can validate your YAML file against a schema. Tools like JSON Schema Validator (despite the name, many support YAML) are valuable for testing your document and quickly spotting the offending line.
  4. Reference Documentation or Examples
    Consult official documentation or working examples to scrutinize your own usage. Comparing your config to trusted templates may reveal the unauthorized property.
  5. Modify or Create a Custom Schema (Advanced)
    If you’re defining your own schema or extending an existing one, you may want to explicitly allow additional properties. In JSON Schema-based validators, you can use:

    "additionalProperties": true

    to allow flexibility. However, only do this if you understand the implications for validation.

Examples of the Error and Fixes

Incorrect GitHub Actions snippet:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        usess: actions/checkout@v2

Fix: The correct key is uses, not usess.

      - name: Checkout code
        uses: actions/checkout@v2

That small typo causes the “property is not allowed” message.

Tips to Avoid the Error in the Future

  • Use a Smart Editor: Use Visual Studio Code or another IDE that provides YAML linting and schema validation.
  • Enable Auto-completion: Use extensions like Red Hat YAML for VS Code to benefit from suggestions.
  • Keep Documentation Handy: Bookmark the relevant schema documentation for the tool or service you’re working with.

Conclusion

The “Property is not allowed” error in YAML is a common stumbling block, but with attention to detail and the right tools, it’s an easily solvable one. Understanding how schemas dictate valid structures and keeping schema-driven validation tools at your disposal ensures that your configurations are not only error-free but also robust and reliable.

So the next time you stumble upon this error, take it as a helpful clue that something isn’t quite right in your YAML, rather than just an annoyance.