> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spendowl.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

# Troubleshooting

Solutions to common issues with the SpendOwl SDK.

## Installation Issues

### Package Not Found

**Error:** `The package at 'https://github.com/spendowl/spendowl-ios' could not be found`

**Solutions:**

1. Check your internet connection
2. Verify the URL is correct: `https://github.com/spendowl/spendowl-ios`
3. Try closing and reopening Xcode
4. Clear the derived data: **Xcode → Settings → Locations → Derived Data → Delete**

### Version Conflicts

**Error:** `Package resolution failed. Dependencies could not be resolved.`

**Solutions:**

1. Update other packages to their latest versions
2. Use a specific version instead of "Up to Next Major":
   ```swift theme={null}
   .package(url: "https://github.com/spendowl/spendowl-ios", exact: "1.0.0")
   ```

***

## Configuration Issues

### SDK Not Configured

**Error:** `SpendOwl SDK is not configured. Call SpendOwl.configure(apiKey:) first.`

**Solution:** Call `configure()` before using other SDK methods:

```swift theme={null}
// In App.init() or AppDelegate
SpendOwl.configure(apiKey: "your-api-key")
```

### Invalid API Key

**Error:** `Invalid API key. Check your SpendOwl dashboard for the correct key.`

**Solutions:**

1. Verify your API key in the [dashboard](https://spendowl.io/dashboard)
2. Ensure you're using the correct environment key (test vs. live)
3. Check for extra spaces or characters in the key

### Configure Called Multiple Times

**Warning:** `SpendOwl already configured, ignoring`

This is informational, not an error. SpendOwl ignores subsequent `configure()` calls. If you need to reconfigure, restart the app.

***

## Attribution Issues

### Attribution Unavailable

**Error:** `Attribution is not available on this device or OS version.`

**Causes:**

* iOS version below 14.3
* Running in the simulator (limited attribution support)
* AdServices framework not available

**Solutions:**

1. Test on a real device with iOS 14.3+
2. Handle gracefully in code:
   ```swift theme={null}
   do {
       let attribution = try await SpendOwl.attribution()
   } catch SpendOwlError.attributionUnavailable {
       // Continue without attribution
   }
   ```

### Attribution Denied

**Error:** `Attribution access was denied.`

**Causes:**

* User has "Limit Ad Tracking" enabled
* MDM profile restricts tracking
* Privacy settings block attribution

**Solution:** This is normal for some users. Handle gracefully and continue.

### Attribution Returns Unknown

**Status:** `AttributionStatus.unknown`

**Possible reasons:**

1. **First launch:** Attribution may take a few seconds to process
2. **Network issues:** Token couldn't be sent to servers
3. **Processing delay:** Server is still resolving the token

**Solution:** Try fetching again after a delay:

```swift theme={null}
// Wait and retry
try await Task.sleep(for: .seconds(2))
let attribution = try await SpendOwl.attribution()
```

### Attribution Always Organic

**Issue:** All installs show as "organic" even when clicking ads

**Causes:**

1. Test device isn't enrolled in Apple Search Ads testing
2. Using a development certificate (attribution may not work)
3. Ad account isn't linked to your app

**Solutions:**

1. Use a TestFlight or App Store build for accurate testing
2. Verify your Apple Search Ads account is properly configured
3. Check the [Apple Search Ads testing guide](https://developer.apple.com/documentation/adservices)

***

## Network Issues

### Request Timeout

**Error:** `Network error: The request timed out.`

**Solutions:**

1. Check internet connectivity
2. Increase timeout:
   ```swift theme={null}
   let config = SpendOwlConfiguration(
       apiKey: "your-api-key",
       timeoutInterval: 30
   )
   SpendOwl.configure(config)
   ```
3. The SDK retries automatically; persistent failures indicate connectivity issues

### Certificate Errors

**Error:** `Network error: The certificate for this server is invalid.`

**Causes:**

* Corporate proxy intercepting HTTPS
* Network security software
* Clock significantly wrong on device

**Solutions:**

1. Disable SSL interception for `spendowl.io`
2. Check device date/time settings

***

## Purchase Tracking Issues

### Purchases Not Appearing

**Issue:** Purchases don't appear in the dashboard

**Causes:**

1. SDK not configured before purchase occurred
2. Using StoreKit 1 instead of StoreKit 2
3. Sandbox purchases with live API key

**Solutions:**

1. Ensure `configure()` is called on app launch
2. SpendOwl only tracks StoreKit 2 transactions
3. Use test API key for sandbox testing

### Sandbox vs Production

**Issue:** Test purchases mixed with production data

**Solution:** Use different API keys:

```swift theme={null}
#if DEBUG
let apiKey = "spendowl_test_xxx"
#else
let apiKey = "spendowl_live_xxx"
#endif
SpendOwl.configure(apiKey: apiKey)
```

***

## Debugging Tips

### Enable Verbose Logging

```swift theme={null}
SpendOwl.logLevel = .debug
```

### Check Console.app

1. Open `/Applications/Utilities/Console.app`
2. Select your device
3. Filter by "SpendOwl"

### Verify Integration

```swift theme={null}
print("Configured: \(SpendOwl.isConfigured)")
print("Version: \(SpendOwl.sdkVersion)")

if let attribution = try? await SpendOwl.attribution() {
    print("Status: \(attribution.status)")
}
```

***

## Still Having Issues?

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/spendowl/spendowl-ios/issues">
    Report a bug or search existing issues
  </Card>

  <Card title="Contact Support" icon="envelope" href="mailto:support@spendowl.io">
    Email [support@spendowl.io](mailto:support@spendowl.io)
  </Card>
</CardGroup>

When reporting issues, include:

* iOS version
* SDK version (`SpendOwl.sdkVersion`)
* Device model (real device vs simulator)
* Debug logs (with sensitive data redacted)
* Steps to reproduce