Limitations and Troubleshooting

Known Limitations and Constraints

Review these constraints before broad rollout.

Anonymous Access Only

PTC currently operates with anonymous access. Redirected requests arrive at Artifactory without authentication credentials.

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 as anonymous redirect traffic
• Audit logs can show anonymous requests unless your environment maps identity during redirect handling
• Per-user tracking depends on your Artifactory, identity, and network integration setup

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 anonymous redirect hop.
• 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.

npm Login Web Flow Fails

npm publish works because PUT requests are not redirected. For users who need to log in and publish packages to the public npm registry (not Artifactory), default npm login (web login) fails because the security edge intercepts a GET call in the login flow (/v1/done callback) and redirects it to Artifactory.

Workarounds:

• Option 1: Add a token directly in .npmrc using npm config set (local config only) — works
• Option 2: Use legacy login: npm login --auth-type legacy — works
• Avoid: Default npm login (web login) — fails

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:

• Route CI through PTC: If CI runners sit behind your security edge, they pick up the same redirect rules automatically.
• Configure CI clients directly: If CI runners are not behind your security edge, point package managers at Artifactory using client config (.npmrc, pip.conf, UV_INDEX_URL, and so on).

Either approach gives a consistent, Artifactory-backed resolution path; choose based on your CI network topology.

Hugging Face Models and Registry Limitations

Gated or licensed models do not work through the anonymous redirect path because it does not carry the developer's Hugging Face token. 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 anonymous 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 anonymous 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 5: 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: Anonymous access is not enabled.
• Solution: Navigate to Administration > Security > Settings, enable Allow Anonymous Access, and ensure anonymous users have read and deploy permissions on the remote repositories.

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 5: Verify the Redirect Endpoint returns something other than HTTP 302 or 307, check these common causes:

• 401 / 403: Anonymous or Router access is not fully configured. Complete Step 4: Configure Anonymous Access and permission targets, 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 /package-reroute on your Artifactory host and that you completed Step 3: Register Repositories with Package Reroute. Use Get Full Configuration 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