# Annotations

Includes API for attaching annotations such as warning messages to constructs.

Obtainable from: Annotations.of

- Source: [`core/lib/annotations.ts`](https://github.com/aws/aws-cdk/blob/v2.277.0/packages/aws-cdk-lib/core/lib/annotations.ts#L32)
- Type last changed: v2.276.0 · 10 Nov 2026

## Example

TypeScript:

```ts
import * as cdk from 'aws-cdk-lib';
import { Construct, IConstruct } from 'constructs';

class MyAspect implements cdk.IAspect {
  public visit(node: IConstruct): void {
    if (node instanceof cdk.CfnResource && node.cfnResourceType === 'Foo::Bar') {
      this.error(node, 'we do not want a Foo::Bar resource');
    }
  }

  protected error(node: IConstruct, message: string): void {
    cdk.Annotations.of(node).addError(message);
  }
}

class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    const stack = new cdk.Stack();
    new cdk.CfnResource(stack, 'Foo', {
      type: 'Foo::Bar',
      properties: {
        Fred: 'Thud',
      },
    });
    cdk.Aspects.of(stack).add(new MyAspect());
  }
}
```

Python:

```python
import aws_cdk as cdk
from constructs import Construct, IConstruct

@jsii.implements(cdk.IAspect)
class MyAspect:
    def visit(self, node):
        if node instanceof cdk.CfnResource && node.cfn_resource_type == "Foo::Bar":
            self.error(node, "we do not want a Foo::Bar resource")

    def error(self, node, message):
        cdk.Annotations.of(node).add_error(message)

class MyStack(cdk.Stack):
    def __init__(self, scope, id):
        super().__init__(scope, id)

        stack = cdk.Stack()
        cdk.CfnResource(stack, "Foo",
            type="Foo::Bar",
            properties={
                "Fred": "Thud"
            }
        )
        cdk.Aspects.of(stack).add(MyAspect())
```

Java:

```java
import software.amazon.awscdk.*;
import software.constructs.Construct;
import software.constructs.IConstruct;

public class MyAspect implements IAspect {
    public void visit(IConstruct node) {
        if (node instanceof CfnResource && node.getCfnResourceType() == "Foo::Bar") {
            this.error(node, "we do not want a Foo::Bar resource");
        }
    }

    public void error(IConstruct node, String message) {
        Annotations.of(node).addError(message);
    }
}

public class MyStack extends Stack {
    public MyStack(Construct scope, String id) {
        super(scope, id);

        Stack stack = new Stack();
        CfnResource.Builder.create(stack, "Foo")
                .type("Foo::Bar")
                .properties(Map.of(
                        "Fred", "Thud"))
                .build();
        Aspects.of(stack).add(new MyAspect());
    }
}
```

C# / .NET:

```csharp
// Install: dotnet add package Amazon.CDK.Lib
using Amazon.CDK;
using Constructs;

class MyAspect : IAspect
{
    public void Visit(IConstruct node)
    {
        if (node instanceof CfnResource && node.CfnResourceType == "Foo::Bar")
        {
            Error(node, "we do not want a Foo::Bar resource");
        }
    }

    protected void Error(IConstruct node, string message)
    {
        Annotations.Of(node).AddError(message);
    }
}

class MyStack : Stack
{
    public MyStack(Construct scope, string id) : base(scope, id)
    {

        var stack = new Stack();
        new CfnResource(stack, "Foo", new CfnResourceProps {
            Type = "Foo::Bar",
            Properties = new Dictionary<string, object> {
                { "Fred", "Thud" }
            }
        });
        Aspects.Of(stack).Add(new MyAspect());
    }
}
```

Golang:

```go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/constructs-go/constructs"

type myAspect struct {
}

func (this *myAspect) visit(node IConstruct) {
	if *node instanceof cdk.CfnResource && *node.CfnResourceType == "Foo::Bar" {
		this.error(*node, jsii.String("we do not want a Foo::Bar resource"))
	}
}

func (this *myAspect) error(node IConstruct, message *string) {
	cdk.Annotations_Of(*node).AddError(*message)
}

type myStack struct {
	Stack
}

func newMyStack(scope Construct, id *string) *myStack {
	this := &myStack{}
	cdk.NewStack_Override(this, scope, id)

	stack := cdk.NewStack()
	cdk.NewCfnResource(stack, jsii.String("Foo"), &CfnResourceProps{
		Type: jsii.String("Foo::Bar"),
		Properties: map[string]interface{}{
			"Fred": jsii.String("Thud"),
		},
	})
	cdk.Aspects_Of(stack).Add(newMyAspect())
	return this
}
```

## Methods

- `acknowledgeInfo(id: string, message?: string): void` — Acknowledge a info. When a info is acknowledged for a scope all infos that match the id will be ignored.

  The acknowledgement will apply to all child scopes

  **Parameters**

  - `id` — - the id of the info message to acknowledge.
  - `message` — optional message to explain the reason for acknowledgement.

  ```ts
  declare const myConstruct: Construct;
  Annotations.of(myConstruct).acknowledgeInfo('SomeInfoId', 'This info can be ignored because...');
  ```

- `acknowledgeWarning(id: string, message?: string): void` — Acknowledge a warning. When a warning is acknowledged for a scope all warnings that match the id will be ignored.

  The acknowledgement will apply to all child scopes

  **Parameters**

  - `id` — - the id of the warning message to acknowledge.
  - `message` — optional message to explain the reason for acknowledgement.

  ```ts
  declare const myConstruct: Construct;
  Annotations.of(myConstruct).acknowledgeWarning('SomeWarningId', 'This warning can be ignored because...');
  ```

- `addDeprecation(api: string, message: string): void` — Adds a deprecation warning for a specific API.

  Deprecations will be added only once per construct as a warning and will be
  deduplicated based on the `api`.

  If the environment variable `CDK_BLOCK_DEPRECATIONS` is set, this method
  will throw an error instead with the deprecation message.

  **Parameters**

  - `api` — The API being deprecated in the format `module.Class.property` (e.g. `@aws-cdk/core.Construct.node`).
  - `message` — The deprecation message to display, with information about alternatives.

- `addError(message: string): void` — Adds an { "error": <message> } metadata entry to this construct.

  The toolkit will fail deployment of any stack that has errors reported against it.
  Prefer using `Validations.of(scope).addError()` instead.

  **Parameters**

  - `message` — The error message.

- `addInfo(message: string): void` — Adds an info metadata entry to this construct.

  The CLI will display the info message when apps are synthesized.

  **Parameters**

  - `message` — The info message.

- `addInfoV2(id: string, message: string): void` — Adds an acknowledgeable info metadata entry to this construct.

  The CLI will display the info when an app is synthesized.

  If the info is acknowledged using `acknowledgeInfo()`, it will not be shown by the CLI.

  **Parameters**

  - `id` — the unique identifier for the info.
  - `message` — The info message.

  ```ts
  declare const myConstruct: Construct;
  Annotations.of(myConstruct).addInfoV2('my-library:Construct.someInfo', 'Some message explaining the info');
  ```

- `addWarning(message: string): void` — Adds a warning metadata entry to this construct. Prefer using `Validations.of(scope).addWarning()`.

  The CLI will display the warning when an app is synthesized, or fail if run
  in `--strict` mode.

  Warnings added by this call cannot be acknowledged. This will block users from
  running in `--strict` mode until the deal with the warning, which makes it
  effectively not very different from `addError`. Prefer using `addWarningV2` instead.

  **Parameters**

  - `message` — The warning message.

- `addWarningV2(id: string, message: string, options?: WarningOptions): void` — Adds an acknowledgeable warning metadata entry to this construct.

  The CLI will display the warning when an app is synthesized, or fail if run
  in `--strict` mode.

  If the warning is acknowledged using `acknowledgeWarning()`, it will not be shown by
  the CLI, and will not cause `--strict` mode to fail synthesis.

  Prefer using `Validations.of(scope).addWarning()` instead.

  **Parameters**

  - `id` — the unique identifier for the warning.
  - `message` — The warning message.
  - `options` — optional settings, including structured `context` describing this occurrence.

  ```ts
  declare const myConstruct: Construct;
  Annotations.of(myConstruct).addWarningV2('my-library:Construct.someWarning', 'Some message explaining the warning');
  ```

- `of(scope: IConstruct): Annotations // chainable` (static) — Returns the annotations API for a construct scope.

  **Parameters**

  - `scope` — The scope.
