Error Handling & Troubleshooting

SDK Errors

The SDK throws SDKError for runtime and validation failures. Each error has a code and optional details. Narrow a caught error with isSDKError() — SDK errors come from the core SDK loaded at runtime, so SDKError is exported as a type only and instanceof SDKError does not compile:

import { isSDKError } from '@vimconnect/app-sdk';

try {
  await sdk.ehr.context.encounter.update({ subjective: { chiefComplaintNotes: 'Headache' } });
} catch (err) {
  if (isSDKError(err)) {
    console.error(`[${err.code}] ${err.message}`, err.details);

    switch (err.code) {
      case 'ENTITY_NOT_IN_CONTEXT':
        // No active encounter — wait for context
        break;
      case 'PERMISSION_REQUIRED':
        // Need to request permission first
        break;
      case 'OPERATION_NOT_CONFIGURED':
        // This EHR doesn't support this operation
        break;
    }
  }
}

Error Codes

Every SDK error is an SDKError carrying a code. Switch on code, not on the message.

Codes below are the SDKErrorCode union, plus NO_WORKER — which the runtime throws but the union does not yet declare, so TypeScript will not autocomplete it.

Connection and initialization

Tokens

Context and writeback

Catalog and manifest

Defensive Patterns

Check Capabilities Before Writing

Always check if an operation is available before attempting it:

const cap = sdk.ehr.context.encounter.getCapability('update');

if (!cap.available) {
  // cap.reason tells you why:
  // - 'not_in_context': no active encounter
  // - 'not_configured': this EHR doesn't support encounter updates
  console.log('Cannot update encounter:', cap.reason);
  return;
}

// Safe to proceed
if (cap.permissionState === 'granted' || !cap.disruptive) {
  await sdk.ehr.context.encounter.update(data);
}

Wrap Context Subscriptions

Not all context keys are available on every EHR. Wrap subscriptions in try-catch:

const manifest = sdk.ehr.getManifest();

for (const ctx of manifest.supportedContexts) {
  try {
    sdk.ehr.context.onChange(ctx.contextKey, (prev, curr) => {
      // Handle context change
    });
  } catch (err) {
    console.warn(`Could not subscribe to ${ctx.contextKey}:`, err);
  }
}

Guard Against Stale Async Results

If your component unmounts or the context changes while an async operation is in flight, the result may be stale:

useEffect(() => {
  let cancelled = false;

  const unsubscribe = sdk.ehr.context.onChange('chart_open:patient', async (prev, curr) => {
    if (!curr) return;

    const result = await sdk.ehr.api.patient.getPatient();
    if (cancelled) return; // component unmounted or context changed

    setPatientData(result.data);
  });

  return () => {
    cancelled = true;
    unsubscribe();
  };
}, [sdk]);

Troubleshooting

"SDK not ready" or Connection Timeout

Symptoms: initVimSDK() throws or hangs, CONNECTION_TIMEOUT error.

Causes:

• The Vim Connect Chrome extension is not installed
• The current page is not a supported EHR
• The extension is disabled or crashed

Solutions:

1. Verify the Chrome extension is installed and enabled at chrome://extensions
2. Confirm you're on a supported EHR page
3. Try reloading the page
4. Check the browser console for extension errors

"Missing launch_id" on Launch Page

Symptoms: Your launch page shows an error about missing launch_id.

Causes:

• Navigating to the launch page directly instead of through the Vim Hub
• The app URL is misconfigured on the Vim platform

Solutions:

1. Always launch through the Vim Hub — don't navigate directly to /launch
2. Verify your app's launch URL is correctly configured on the Vim platform

OAuth Token Exchange Fails

Symptoms: 401 or 400 error from /app-auth/token.

Causes:

• Invalid or expired authorization code (codes are single-use)
• Wrong client_id or client_secret
• Mismatched redirect_uri (must exactly match the registered URL)
• Using staging credentials against production backend, or vice versa

Solutions:

1. Verify NEXT_PUBLIC_CLIENT_ID and CLIENT_SECRET match your app registration
2. Ensure NEXT_PUBLIC_ENV matches the environment your app is registered in
3. Check that your redirect_uri exactly matches the registered callback URL
4. Re-launch the app to get a fresh authorization code

Context Data is Empty

Symptoms: onChange fires but curr.fields is empty or missing expected data.

Causes:

• The EHR hasn't finished loading the data yet
• The field isn't available for this specific EHR system

Solutions:

1. Context updates fire progressively — fields populate as the extension extracts them. Wait for subsequent updates.
2. Check sdk.ehr.getManifest().supportedEntities to see which fields are available for the current EHR.

Writeback Has No Effect

Symptoms: update() returns success but the EHR doesn't change.

Causes:

• The provider is on a read-only screen
• The EHR requires specific navigation state for writeback
• The field isn't writable for this EHR configuration

Solutions:

1. Check getCapability('update') — if available is false, the current screen doesn't support it
2. Verify the field path matches what the manifest reports as writable
3. Check getManifest().contextWriteback for the entity's updatableFields list

Debug Mode

Enable debug logging to see all SDK communication:

const sdk = await initVimSDK({ debug: true });

This logs all messages between your app and the extension to the browser console, including:

• Event dispatches
• Context updates
• API calls and responses
• Permission requests