Limitations and Troubleshooting

Known Limitations and Constraints

Review these constraints before broad rollout.

Private and Scoped Packages

PTC redirects traffic through the _package-reroute system user and does not forward developer credentials. This means:

Impact:

• Only public packages from public registries can be redirected and served
• Private and scoped packages requiring authentication (for example, @company/private-package on npm) are not supported through the PTC redirect path
• Audit logs show requests as the _package-reroute system user — individual developer identity is not captured on PTC-redirected requests

Workarounds:

• Direct client access: Configure the package manager to reach Artifactory (or the upstream registry) with credentials (for example, .npmrc for npm, pip.conf for pip), bypassing the PTC redirect.
• Artifactory-side credentials: Storing upstream credentials on the PTC remote repository can allow some gated public-registry content to resolve. Validate this pattern for your ecosystem before production use. Hugging Face gated models are called out explicitly under Hugging Face models and registry limitations.

POST-Based Commands Not Redirected

Commands that use HTTP POST are explicitly excluded from the redirect rules to prevent failures. npm is documented in detail in Configuration by package type. Other clients (including Python tooling) may use POST to registry hosts. Confirm with your security edge logs and keep non-GET methods off the redirect rule unless you have tested them.

Implication: These commands are not covered by JFrog Curation policies and will not appear in the Artifactory audit trail.

CI/CD Consistency

PTC governs traffic from workstations where a security edge client is running. CI/CD runners often use a different network path, so package resolution can diverge from developer workstations unless explicitly configured.

To keep resolution consistent across both environments:

• Configure CI clients directly: Point package managers at Artifactory using client config (.npmrc, pip.conf, UV_INDEX_URL, and so on).

This gives a consistent, Artifactory-backed resolution path regardless of your CI network topology.

Hugging Face Models and Registry Limitations

Gated or licensed models do not work through the PTC redirect path because developer credentials are not forwarded. Mitigation: Configure the Hugging Face remote repository (the PTC repo_key for huggingfaceml) with stored Hugging Face credentials so Artifactory authenticates to the upstream on behalf of redirected requests. Follow JFrog's Hugging Face integration documentation for the repository configuration steps.

Xet transfer protocol is not supported through the PTC redirect flow. To use PTC with Hugging Face, disable Xet on the workstation:

HF_HUB_DISABLE_XET=1

This is a workstation-wide setting; it affects all Hugging Face downloads from that machine and falls back to standard HTTPS, which may be slower for large model files. If the workstation is later switched to talk directly to Artifactory's Hugging Face repository with credentials (instead of the PTC redirect path), remove the variable so Xet transfers resume.

Strict SSL Certificate Validation in Python Tools

Python-based package tools use Python's built-in ssl module, which requires RFC 5280-compliant certificates. If your security edge uses a non-compliant certificate, some Python tools encounter TLS errors. Tools that bypass the Python ssl module (pip ≥ 24.2 via truststore, uv via Rust TLS) are unaffected.

Fix: ask your security edge administrator to issue an RFC 5280-compliant CA certificate (most providers have done so since mid-2024). See Strict SSL Certificate Validation in Python Tools for the full compatibility matrix and resolution steps.

Netskope: Certificate critical Extension (Hugging Face and Poetry)

When using Netskope as your SASE, Python's strict (RFC 5280) certificate verification requires the CA certificate to include the critical flag / key-usage extension. If the Netskope-injected certificate does not include these, Hugging Face and Poetry installs fail through Netskope. pip, uv, npm, and yarn are unaffected.

Workaround: Use a CA certificate that includes the required critical extensions for the Netskope tenant. This mirrors the general Strict SSL Certificate Validation in Python Tools constraint.

Older Package Manager Versions

Troubleshooting

Verifying the Setup

Client-Side Checks

Run these from a developer workstation with your SASE provider's client active (for example, Zscaler Client Connector or Netskope Client).

1. Verify the security edge client is running. The macOS menu bar or Windows system tray icon should show a connected state. On Linux, confirm the client your IT team uses is running (the exact check depends on the installation).

2. Verify SSL inspection is active. Replace registry.npmjs.org with the host you intercept for other ecosystems.

openssl s_client -connect registry.npmjs.org:443 -servername registry.npmjs.org 2>/dev/null | openssl x509 -noout -issuer

If SSL inspection is active, the issuer names your security edge CA (for example CN=Zscaler Root CA or CN=Netskope Certificate Authority), not the original registry's CA.

Verify NODE_EXTRA_CA_CERTS points at the security edge CA bundle:

openssl x509 -in "$NODE_EXTRA_CA_CERTS" -noout -issuer

Expected: the issuer line matches your security edge CA.

Check That the Redirect Is Working

3. Verify Redirect Is Working

curl -v -L "https://registry.npmjs.org/express" 2>&1 | grep -i "location"

You should see a Location header pointing to your Artifactory instance.

4. Verify Package Install Works

# Test end-to-end (--loglevel verbose shows GETs so you can confirm traffic hits Artifactory)
npm install express --loglevel verbose
# Example: look for GET 200 https://<YOUR_ARTIFACTORY_URL>/artifactory/api/npm/npm-remote-registry/express

The command should complete successfully with the package resolved through Artifactory.

Server-Side Checks

1. Verify redirect endpoint. Use the full curl test, encoding rules, and expected 302/307 behavior in Step 4: Verify the Redirect Endpoint only (Router /package-reroute, not /artifactory/api/package-reroute/...).

2. Verify Packages Are Cached

Open Artifactory > Artifacts, navigate to the remote repository, and confirm the package appears.

3. Verify Curation Audit Log (if Curation is enabled)

Navigate to Curation > Audit and confirm recent entries with package name, policy decision, and timestamp. If Curation is not in use, omit this check.

Common Issues and Solutions

Issue: Package Install Fails with SSL Error

• Symptom: SSL certificate problem or UNABLE_TO_GET_ISSUER_CERT_LOCALLY.
• Cause: The security edge CA is not trusted by the OS, or NODE_EXTRA_CA_CERTS is missing or points to the wrong file. Verify with openssl x509 -in "$NODE_EXTRA_CA_CERTS" -noout -issuer; it should match your security edge Root CA.
• Fix: Distribute the certificate and environment variables through your standard workstation process (MDM, endpoint tooling, or another repeatable method).

Issue: Package Install Fails with 403 Forbidden

• Symptom: HTTP 403 error from Artifactory.
• Cause: The _package-reroute user does not have the required permissions on the remote repository, or the Package Reroute configuration endpoint has not been called.
• Solution: Call PUT /artifactory/api/package-reroute/config/{type} to register the repository. See Step 3: Register Repositories with Package Reroute.

Issue: npm audit Fails

• Symptom: npm audit returns an error or unexpected redirect response.
• Cause: POST requests are being redirected.
• Solution: Verify that the URL Filtering rule only includes GET and HEAD request methods.

Issue: Package Install Succeeds but Package Not Visible in Artifactory

• Symptom: npm install succeeds, but the package does not appear in Artifactory.
• Cause: The package was served from the local npm cache.
• Solution:
  Shell

  npm cache clean --force && npm install <PACKAGE_NAME>

Issue: Redirect Not Working (Traffic Goes Directly to Public Registry)

• Possible causes:
  1. Security edge client not running on the workstation
  2. SSL Inspection rule not above default bypass rules
  3. URL category mismatch (e.g., registry.npmjs.org vs npmjs.org)
  4. User not in the target group (scoped deployment)
  5. Policy not activated after configuration

Verify the Redirect Endpoint Troubleshooting

If Step 4: Verify the Redirect Endpoint returns something other than HTTP 302 or 307, check these common causes:

• 401 / 403: The _package-reroute user may not be set up. Ensure you have called Step 3: Register Repositories with Package Reroute successfully, then retry.
• 407 (Proxy Authentication Required): The request reached a proxy that requires authentication. Ensure the client or security edge/proxy is configured to authenticate, then retry.
• 404 / wrong path: Confirm your security edge's redirect URL uses /artifactory/api/package-reroute on your Artifactory host and that you completed Step 3: Register Repositories with Package Reroute. Use Get Full Configuration (GET /artifactory/api/package-reroute/config; see Package Reroute Config API) to confirm repo_key for npm is set.
• Very long url= values: Some clients require URL-encoding the url query parameter; if the bare string fails, encode the registry URL portion.

For rollback procedures (quick rollback, full security edge rollback, and verification), see Rollback Process in Deploy and Roll Out PTC.

Frequently Asked Questions

This section provides answers to frequently asked questions about PTC limitations and troubleshooting.

Related Topics

• Package Traffic Controller (PTC) overview
• Configuration by Package Type
• Configure Artifactory for PTC