{"id":7019,"library":"aws-cdk-asset-node-proxy-agent-v5","title":"AWS CDK Asset Node.js Proxy Agent v5","description":"The `aws-cdk-asset-node-proxy-agent-v5` library provides an AWS CDK Construct that configures Node.js-based assets (e.g., Lambda functions) to use an HTTP/HTTPS proxy during their build and bundling phases. This is critical for CDK deployments in corporate environments where internet access requires going through a proxy, leveraging the `proxy-agent` Node.js library. It is an experimental construct from `cdklabs` and is currently at version 2.0.166, aligning with AWS CDK v2 releases, with updates tied to CDK's release cadence.","status":"active","version":"2.0.166","language":"en","source_language":"en","source_url":"https://github.com/cdklabs/awscdk-asset-node-proxy-agent.git","tags":["aws-cdk","cdk-v2","proxy","nodejs","lambda","assets","networking"],"install":[{"cmd":"pip install aws-cdk-asset-node-proxy-agent-v5","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This is an AWS CDK Construct and requires the core CDK library.","package":"aws-cdk-lib","optional":false},{"reason":"Underlying dependency for all CDK constructs.","package":"constructs","optional":false}],"imports":[{"note":"Python packages use underscores for their module names, not hyphens, despite PyPI name.","wrong":"from aws_cdk.asset_node_proxy_agent_v5 import NodeProxyAgent","symbol":"NodeProxyAgent","correct":"from aws_cdk_asset_node_proxy_agent_v5 import NodeProxyAgent"}],"quickstart":{"code":"import os\nfrom aws_cdk import App, Stack, Environment\nfrom aws_cdk.aws_lambda_nodejs import NodejsFunction\nfrom aws_cdk_asset_node_proxy_agent_v5 import NodeProxyAgent\n\n\nclass MyProxyStack(Stack):\n    def __init__(self_stack, scope, id, **kwargs):\n        super().__init__(scope, id, **kwargs)\n\n        # Define proxy configuration - ensure these env vars are set in your build environment\n        http_proxy = os.environ.get('HTTP_PROXY', '')\n        https_proxy = os.environ.get('HTTPS_PROXY', '')\n        no_proxy = os.environ.get('NO_PROXY', '')\n\n        if http_proxy or https_proxy:\n            # Instantiate the NodeProxyAgent construct\n            NodeProxyAgent(self_stack, \"NodeProxyAgent\",\n                           http_proxy=http_proxy,\n                           https_proxy=https_proxy,\n                           no_proxy=no_proxy\n            )\n            print(f\"NodeProxyAgent configured with HTTP_PROXY: {http_proxy} and HTTPS_PROXY: {https_proxy}\")\n        else:\n            print(\"No proxy environment variables found. NodeProxyAgent not configured.\")\n\n        # Example Node.js Lambda function, its bundling will use the configured proxy\n        NodejsFunction(\n            self_stack, \"MyProxyEnabledFunction\",\n            entry=\"./lambda/index.ts\", # Replace with your Node.js Lambda entry point\n            handler=\"handler\",\n            memory_size=128\n        )\n\n\napp = App()\nMyProxyStack(app, \"MyProxyEnabledStack\",\n             env=Environment(account=os.environ.get('CDK_DEFAULT_ACCOUNT', '123456789012'),\n                             region=os.environ.get('CDK_DEFAULT_REGION', 'us-east-1'))\n)\napp.synth()","lang":"python","description":"This quickstart demonstrates how to integrate `NodeProxyAgent` into your CDK application. It sets up an `NodeProxyAgent` instance to configure proxy settings for Node.js assets during synthesis, using environment variables for proxy URLs. A sample `NodejsFunction` is included, which will then use these proxy settings during its bundling process."},"warnings":[{"fix":"Understand the distinction between build-time and runtime proxying. For runtime proxying, use Lambda environment variables or a custom layer that configures `https-proxy-agent` or similar.","message":"The `NodeProxyAgent` configures proxy settings for Node.js *asset bundling* (e.g., when `NodejsFunction` builds its code package). It does NOT configure runtime proxy settings for the deployed Lambda function itself. If your Lambda needs to egress through a proxy at runtime, that must be configured separately.","severity":"gotcha","affected_versions":"All v2.x.x"},{"fix":"Ensure your Node.js asset's dependencies and build environment are compatible with `proxy-agent` v5. If using a different version, consider if this construct is necessary or if manual configuration is more appropriate.","message":"This construct is specific to Node.js `proxy-agent` v5. If your project relies on an older or newer major version of `proxy-agent` in a custom build step, this construct might not be compatible or could override existing configurations unexpectedly.","severity":"breaking","affected_versions":"All v2.x.x"},{"fix":"Explicitly pass all required proxy settings (including `no_proxy`) to the `NodeProxyAgent` constructor. Do not rely solely on environment variables if the construct is instantiated with parameters, as parameters take precedence.","message":"The `http_proxy`, `https_proxy`, and `no_proxy` arguments to `NodeProxyAgent` override any existing `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` environment variables *during the asset bundling process*. Ensure your construct parameters correctly reflect the desired proxy configuration.","severity":"gotcha","affected_versions":"All v2.x.x"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change the import statement to `from aws_cdk_asset_node_proxy_agent_v5 import NodeProxyAgent`.","cause":"Incorrect import path. Python packages convert hyphens in their PyPI names to underscores for module names.","error":"ModuleNotFoundError: No module named 'aws_cdk.asset_node_proxy_agent_v5'"},{"fix":"Ensure that the CA certificate is available and trusted within your CDK build environment, potentially by setting the `NODE_EXTRA_CA_CERTS` environment variable or adding the certificate to the system trust store.","cause":"Often seen when using a corporate proxy with SSL interception, and the certificate authority (CA) certificate is not trusted by the Node.js environment during asset bundling.","error":"Error: unable to get local issuer certificate"},{"fix":"Double-check the `http_proxy`, `https_proxy`, and crucially, the `no_proxy` settings passed to `NodeProxyAgent`. Ensure `no_proxy` includes internal hosts that should bypass the proxy. Verify proxy server accessibility.","cause":"Node.js package manager (npm) cannot resolve hostnames, often indicating a misconfigured proxy, incorrect `NO_PROXY` settings, or network issues.","error":"npm ERR! code ENOTFOUND"}]}