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:
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()
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 datasetsapi:write-data — write datasetsapi:ontology-read — read Ontology objectsapi: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:
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)
return data.select("fullName")
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"])
@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
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
Next Steps
For deeper debugging, see palantir-debug-bundle.
