palantir-common-errors

Palantir Common Errors

Overview

Quick reference for the top 10 most common Foundry API and transform errors with copy-paste solutions.

Prerequisites

• foundry-platform-sdk installed
• API credentials configured
• Access to Foundry build logs or application logs

Instructions

Error 1: 401 Unauthorized — Invalid or Expired Token

foundry.ApiError: 401 Unauthorized — The provided token is invalid or expired.

Fix:

# Regenerate token in Developer Console
# Settings > Tokens > Generate new personal access token
# Or re-authenticate with OAuth2:
auth = foundry.ConfidentialClientAuth(
    client_id=os.environ["FOUNDRY_CLIENT_ID"],
    client_secret=os.environ["FOUNDRY_CLIENT_SECRET"],
    hostname=os.environ["FOUNDRY_HOSTNAME"],
    scopes=["api:read-data"],
)
auth.sign_in_as_service_user()  # Gets a fresh token

Error 2: 403 Forbidden — Insufficient Scopes

foundry.ApiError: 403 Forbidden — Missing required scope: api:ontology-read

Fix: Add missing scopes in Developer Console > Your App > Scopes. Common scopes:

• api:read-data — read datasets
• api:write-data — write datasets
• api:ontology-read — read Ontology objects
• api:ontology-write — apply actions

Error 3: ObjectTypeNotFound

foundry.ApiError: 404 ObjectTypeNotFound — Object type 'employee' not found

Fix: Object type names are camelCase API names, not display names. Check Ontology Manager:

# List all object types to find the correct api_name
for ot in client.ontologies.ObjectType.list(ontology="my-company"):
    print(f"  {ot.api_name} (display: {ot.display_name})")

Error 4: DatasetNotFound

foundry.ApiError: 404 DatasetNotFound — Dataset not found or you do not have access

Fix: Verify the dataset RID (right-click dataset in Foundry UI > Copy RID). Ensure your service user has Viewer/Editor role on the project.

Error 5: Transform Build AnalysisException

pyspark.sql.utils.AnalysisException: cannot resolve 'fullname' given columns [fullName, department]

Fix: Spark column names are case-sensitive. Print columns to debug:

@transform_df(Output("/out"), data=Input("/in"))
def my_transform(data):
    print(data.columns)  # Check actual column names
    return data.select("fullName")  # Use exact casing

Error 6: OutOfMemoryError in Transform Builds

java.lang.OutOfMemoryError: Java heap space

Fix: Add @configure with a larger memory profile:

from transforms.api import configure
@configure(profile=["DRIVER_MEMORY_LARGE"])  # 16GB
@transform_df(Output("/out"), data=Input("/in"))
def heavy_transform(data):
    return data.groupBy("region").agg({"amount": "sum"})

Error 7: ActionValidationFailed

foundry.ApiError: ActionValidationFailed — Parameter 'salary' must be positive

Fix: Read the validation messages for specific constraint violations:

result = client.ontologies.Action.apply(
    ontology="my-company",
    action_type="updateSalary",
    parameters={"employeeId": "EMP-001", "salary": 150000},
)
if result.validation != "VALID":
    for msg in result.validation_messages:
        print(f"  Validation error: {msg}")

Error 8: ConnectionError / SSL Error

requests.exceptions.SSLError: SSL certificate verify failed

Fix: Common behind corporate proxies. Set the CA bundle:

export REQUESTS_CA_BUNDLE=/path/to/corporate-ca-bundle.crt
# Or for development only (NOT production):
export FOUNDRY_SSL_VERIFY=false

Error 9: Rate Limit 429

foundry.ApiError: 429 Too Many Requests — Rate limit exceeded

Fix: See palantir-rate-limits for full implementation. Quick fix:

import time
time.sleep(int(response.headers.get("Retry-After", 5)))

Error 10: Circular Dependency in Transforms

Build failed: Circular dependency detected between datasets

Fix: Dataset A's transform reads from B, and B reads from A. Break the cycle by introducing an intermediate dataset or restructuring the pipeline DAG.

Output

• Identified error from Foundry API response or build logs
• Applied targeted fix
• Verified resolution with successful API call or build

Error Handling

HTTP Code	Meaning	Retryable
400	Bad Request (invalid params)	No — fix request
401	Token expired/invalid	No — re-authenticate
403	Missing scopes	No — update app scopes
404	Resource not found	No — fix identifier
429	Rate limited	Yes — wait and retry
500/502/503	Server error	Yes — retry with backoff

Resources

• Foundry API Reference
• Transforms Python API

Next Steps

For deeper debugging, see palantir-debug-bundle.