Troubleshoot connectivity

Connectivity issues may arise if you're trying to use the Dynatrace App Toolkit from a company network. These can include network issues, proxy issues, firewall issues, single sign-on issues, etc. The following guide will help you solve those issues.

Install the latest version

First, ensure you're using the latest version of Dynatrace App Toolkit before troubleshooting. The latest version is available at the public npm registry.

You should also ensure you're using a Node.js version officially supported by the Dynatrace App Toolkit (usually the latest LTS version of Node.js). Dynatrace App Toolkit will warn you if you use a Node.js version that's not officially supported with the following message:

dt-app is operating in an unofficially supported Node.js environment.
To prevent potential issues, it's recommended to utilize the app with Node.js ${majorNode.jsVersion}.

If you see this message, adjust the version of your Node.js environment accordingly.

Verify access to the npm registry

You should also confirm that npm has access to the registry by running the following command in the terminal:

npm ping

Following is the expected output:

npm notice PING https://registry.npmjs.org/
npm notice PONG 335ms

This output means that npm has access to the public registry. If npm doesn't have access to the official registry, this hints towards a networking issue likely caused by a proxy or firewall in your network. Configure your network and your machine in a way that allows npm and, subsequently, the Dynatrace App Toolkit to access the public npm repository.

Troubleshooting

This guide helps identify connectivity issues when accessing Dynatrace resources on your corporate network. Follow the commands and compare your machine's outputs with the expected ones. If there are any deviations, go to the connectivity issues section to troubleshoot.

You need to replace the Environment-Id with your actual environment ID in the following examples.

Connectivity of your machine

You'll see if you can access Dynatrace Single Sign-On (SSO) and your environment.

Access Single Sign-On server

To start, check if your machine can access the Dynatrace environment using curl or a similar tool. It tests whether you can reach the Dynatrace Single Sign-On server and whether your machine can access hosts outside your corporate network.

curl -I https://sso.dynatrace.com

The following output containing a 200 OK is expected:

HTTP/2 200
...

Show full example response output

HTTP/2 200
date: Thu, 01 Feb 2024 10:10:10 GMT
content-type: text/html
content-length: 2281
set-cookie: ; Expires=Thu, 10 Feb 2024 10:10:10 GMT; Path=/
set-cookie: ; Expires=Thu, 10 Feb 2024 10:10:10 GMT; Path=/; SameSite=None; Secure
x-frame-options: deny
frame-options: deny
x-xss-protection: 1; mode=block
x-content-type-options: nosniff
content-security-policy: default-src 'self' https://static.sso.dynatrace.com https://dt-cdn.net; script-src 'self' https://www.google.com/recaptcha/ https://www.gstatic.com/recaptcha/ https://static.sso.dynatrace.com ; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://dt-cdn.net https://static.sso.dynatrace.com; frame-ancestors 'none'; frame-src 'self' https://www.google.com/recaptcha/
x-content-security-policy: default-src 'self' https://static.sso.dynatrace.com https://dt-cdn.net; script-src 'self' https://www.google.com/recaptcha/ https://www.gstatic.com/recaptcha/ https://static.sso.dynatrace.com ; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com https://dt-cdn.net https://static.sso.dynatrace.com; frame-ancestors 'none'; frame-src 'self' https://www.google.com/recaptcha/
strict-transport-security: max-age=31536000; preload
cache-control: private, no-store, must-revalidate
pragma: no-cache
set-cookie: b925d32c=; Path=/; Domain=sso.dynatrace.com; Expires=Thu, 01-Jan-1970 00:00:00 GMT; Max-Age=0; Secure; HttpOnly; SameSite=None
set-cookie: ssoCSRFCookie=; Path=/; Domain=.dynatrace.com; Expires=Thu, 01-Jan-1970 00:00:00 GMT; Max-Age=0; Secure; SameSite=None

The Dynatrace SSO server is reachable and responding to your requests. It also means your machine can reach hosts outside your corporate network.

Access your environment

The following command checks if you can access your Dynatrace environment to access your data. This tests if your specific environment is reachable.

curl -I https://<Environment-Id>.apps.dynatrace.com/

The following output containing a 401 Unauthorized status is expected, as you aren't yet authenticated.

HTTP/2 401
...

It means your environment is reachable from your machine within the corporate network, and your Dynatrace environment is available.

The last command is to check access to your Dynatrace environment with SSO authentication and whether you can facilitate the authentication process. The authentication process is complex, sending and receiving many requests and responses.

curl -I https://<Environment-Id>.apps.dynatrace.com/platform/oauth2/authorization/dynatrace-sso

The following output containing a 302 Found status is expected:

HTTP/2 302
...

It means that Dynatrace SSO is reachable for the authentication for your Dynatrace environment. You get a 302 in this case because curl doesn't follow redirects.

If you don't receive these outputs, refer to this guide's connectivity issues section. If you have gotten those outputs, try the same Node.js procedure to ensure the Node.js application has identical connectivity. Sometimes, Node.js is blocked from accessing the outside network within corporate networks. Follow along in the next section of this guide.

Connectivity of Node.js

As Node.js is your app's main development environment, access to all relevant resources is necessary. Check the following commands to ensure that Node.js is working correctly.

Access Single Sign-On server

Execute the first command to access Dynatrace SSO:

node -e "fetch('https://sso.dynatrace.com').then(console.log)"

The following output containing a 200 OK is expected:

 ...
 status: 200,
 ...
 statusText: 'OK',
 ...

Show full example response output

Response {
  [Symbol(realm)]: null,
  [Symbol(state)]: {
    aborted: false,
    rangeRequested: false,
    timingAllowPassed: true,
    requestIncludesCredentials: true,
    type: 'default',
    status: 200,
    timingInfo: {
      startTime: 39.133354,
      redirectStartTime: 0,
      redirectEndTime: 0,
      postRedirectStartTime: 39.133354,
      finalServiceWorkerStartTime: 0,
      finalNetworkResponseStartTime: 0,
      finalNetworkRequestStartTime: 0,
      endTime: 0,
      encodedBodySize: 1270,
      decodedBodySize: 0,
      finalConnectionTimingInfo: null
    },
    cacheState: '',
    statusText: 'OK',
    headersList: HeadersList {
      cookies: [Array],
      [Symbol(headers map)]: [Map],
      [Symbol(headers map sorted)]: null
    },
    urlList: [ URL {} ],
    body: { stream: undefined }
  },
  [Symbol(headers)]: HeadersList {
    cookies: [],
    [Symbol(headers map)]: Map(18) {
      'date' => [Object],
      'content-type' => [Object],
      'content-length' => [Object],
      'connection' => [Object],
      'set-cookie' => [Object],
      'server-timing' => [Object],
      'x-oneagent-js-injection' => [Object],
      'x-frame-options' => [Object],
      'frame-options' => [Object],
      'x-xss-protection' => [Object],
      'x-content-type-options' => [Object],
      'content-security-policy' => [Object],
      'x-content-security-policy' => [Object],
      'strict-transport-security' => [Object],
      'cache-control' => [Object],
      'pragma' => [Object],
      'vary' => [Object],
      'content-encoding' => [Object]
    },
    [Symbol(headers map sorted)]: null
  }
}

Access your environment

Execute the following command to see if you can access your Dynatrace environment:

node -e "fetch('https://<Environment-Id>.apps.dynatrace.com').then(console.log)"

The following output containing a 401 Unauthorized status is expected, as you aren't yet authenticated.

 ...
 status: 401,
 ...
 statusText: 'Unauthorized',
 ...

Execute the following command to see if you can access the authorization APIs of your environment:

node -e "fetch('https://<Environment-Id>.apps.dynatrace.com/platform/oauth2/authorization/dynatrace-sso').then(console.log)"

The following output containing a 200 OK status is expected:

 ...
 status: 200,
 ...
 statusText: 'OK',
 ...

If you don't receive these outputs, refer to this guide's connectivity issues section.

If you did receive these outputs, everything should work as expected if you develop your app with the help of Dynatrace App Toolkit.

Connectivity issues

If you don't receive the desired outputs of the above commands, several problems might occur. The most common error messages are outlined in the following table and usually indicate a proxy or firewall issue.

CURL Error	Node.js Error	Interpretation
CURLE_COULDNT_RESOLVE_HOST	ENOTFOUND	The host couldn't be found, something is blocking DNS resolution.
CURLE_OPERATION_TIMEDOUT	ETIMEDOUT	The host couldn't be reached, the request timed out.
CURLE_REMOTE_ACCESS_DENIED	ECONNREFUSED	The connection was refused by some entity, either the host or some other server.
CURLE_RECV_ERROR	ECONNRESET	The connection has been reset by some entity, either the client or some other server.

If you need further information or experience issues not listed here, refer to the curl documentation for detailed information curl. This can help identify your error more quickly. If you find different HTTP error codes, refer to HTTP response status codes for more details. The most likely culprits in this respect are misconfigured proxy servers and enterprise firewall software.

Proxy server

If your company requires a proxy server for outbound connections, ensure the proxy server is set correctly.

Use the following commands to check if a proxy server (for HTTP and HTTPS connections) is configured on your machine:

echo %https_proxy%

echo %http_proxy%

Adjust the proxy settings according to your company settings and operating system. An enterprise firewall might be the culprit if your issue persists with a correctly configured proxy server.

Firewall

If the proxy isn't the culprit, an enterprise firewall might be actively tampering with connections. Dynatrace App Toolkit is a relatively unknown application. It might be blocked by default in enterprise firewall products, hindering access to the Dynatrace environment. Make sure to unblock the Dynatrace App Toolkit in the corporate firewall or create specific firewall rules to allow as unrestricted access as possible for the Dynatrace App Toolkit.

A common issue you might find is the SELF_SIGNED_CERT_IN_CHAIN error. You can work around this by adding your PEM certificate to the NPM config with the following command:

npm config set cafile /path/to/cert.pem

Contact your in-house IT department for further assistance if you run into any proxy server or firewall issues.

GitHub access

If none of the previous solutions work, there's a workaround that might help. When you create a new app with the Dynatrace App Toolkit, it fetches the templates for scaffolding your app from GitHub. Sometimes this process might fail due to your system's restrictions. You can work around this by downloading the templates manually, and using the --template-dir option from the Dynatrace App Toolkit.

npx dt-app@latest create --template-dir ./path-to-templates-repo/templates/default