Developer Guide

Troubleshooting AWS X-Ray

This topic lists common errors and issues that you might encounter when using the X-Ray API, console, or SDKs. If you find an issue that is not listed here, you can use the Feedback button on this page to report it.

X-Ray SDK for Java

Error: Exception in thread "Thread-1" com.amazonaws.xray.exceptions.SegmentNotFoundException: Failed to begin subsegment named 'AmazonSNS': segment cannot be found.

This error indicates that the X-Ray SDK attempted to record an outgoing call to AWS, but couldn't find an open segment. This can occur in the following situations:

  • A servlet filter is not configured – The X-Ray SDK creates segments for incoming requests with a filter named AWSXRayServletFilter. Configure a servlet filter to instrument incoming requests.

  • You're using instrumented clients outside of servlet code – If you use an instrumented client to make calls in startup code or other code that doesn't run in response to an incoming request, you must create a segment manually. See Instrumenting Startup Code for examples.

  • You're using instrumented clients in worker threads – When you create a new thread, the X-Ray recorder loses its reference to the open segment. You can use the getTraceEntity and setTraceEntity methods to get a reference to the current segment or subsegment (Entity), and pass it back to the recorder inside of the thread. See Using Instrumented Clients in Worker Threads for an example.

X-Ray SDK for Node.js

Issue: CLS does not work with Sequelize

Pass the X-Ray SDK for Node.js namespace to Sequelize with the cls method.

var AWSXRay = require('aws-xray-sdk'); const Sequelize = require('sequelize'); Sequelize.cls = AWSXRay.getNamespace(); const sequelize = new Sequelize('database', 'username', 'password');

Issue: CLS does not work with Bluebird

Use cls-bluebird to get Bluebird working with CLS.

var AWSXRay = require('aws-xray-sdk'); var Promise = require('bluebird'); var clsBluebird = require('cls-bluebird'); clsBluebird(AWSXRay.getNamespace());

The X-Ray daemon

Issue: The daemon is using the wrong credentials

The daemon uses the AWS SDK to load credentials. If you use multiple methods of providing credentials, the method with the highest precedence is used. See Running the Daemon for more information.