# Fix onboarding agent crashing on null SSO profile after HR import failed

## TL;DR
The agent crashes because it assumes the HR import produced a profile, but the import failed and left null. Check the import result before touching the profile, and fail with a clear message when the import failed. Null is the import telling you it did not run.

## The error
```text
Onboarding agent crashed
Null SSO profile after HR import failed. Cannot read properties of null.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=onboarding agent crashed on null sso profile after hr import failed"
```

## Fix it

### Step 1: Check the HR import result first

```bash
Before reading the profile, verify the import succeeded.
```

Expected: The agent knows whether there is a profile to read.

### Step 2: Handle the failed import explicitly

```bash
On import failure, stop and report the import error instead of continuing.
```

Expected: Failures surface as import errors, not null crashes.

### Step 3: Add null guards on the profile

```bash
Defensively check the profile before dereferencing it.
```

Expected: A missing profile becomes a clear error, never a crash.

### Step 4: Fix the underlying import failure

```bash
Address whatever broke the HR import.
```

Expected: Imports succeed and profiles exist.

### Step 5: Re-run onboarding

```bash
Run the onboarding flow again.
```

Expected: It completes without null crashes.

## When this applies

- Agents crash on null profiles after failed imports
- Onboarding dies with null reference errors
- You are chaining HR imports into provisioning

## When it doesn't

- The import succeeds but the profile is wrong (check the mapping)
- The profile is null for another reason (trace the actual source)
- The SSO config is broken (fix the SSO)

## Compatibility

HR import to SSO provisioning chains. Any agent framework.

## Variant phrasings

### agent crash null profile import failed

Same crash. Check the import result before the profile.

### null sso profile onboarding agent

Null profiles always trace to a failed upstream step. Fix upstream.

### cannot read properties of null onboarding

The null is a symptom. The disease is the unchecked import failure.

## Why it happens

Chained agent steps often assume the previous step succeeded. When the HR import fails silently or its failure is ignored, the profile variable stays null and the next step crashes dereferencing it. Checking step results before proceeding is the basic contract of a pipeline.

## Edge cases

- Partial imports can leave half a profile; validate completeness, not just non-null
- Log the import's error alongside the null so the chain is debuggable
- Retries of the import need idempotency so a second run does not duplicate

## If it still fails

- Reproduce with a minimal run: one user, one file, one step.
- Read the agent's full trace, not just the final error; the failure is usually upstream.
- Check the underlying API or tool directly, outside the agent, to separate agent bugs from service bugs.
- Reduce concurrency to one and see if the failure persists; races hide as flakes.
- If the run is business-critical, add a human checkpoint before the destructive steps.

## Prevention

- Checkpoint long runs so any failure resumes instead of restarting.
- Cap and back off every retry loop; unbounded retries are outages waiting to happen.
- Validate inputs at each pipeline stage; fail fast with clear errors.
- Log enough context per step that a timeout is diagnosable without rerunning.
- Give destructive steps a human checkpoint or a dry-run mode.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cmIdaBzhe75GqCYrENCmqg