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');