---
title: "Troubleshooting Common Issues"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Troubleshooting Common Issues}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

This vignette addresses the most common issues users encounter when setting up and using the `tuber` package.

## HTTP 403 Errors

### Error: "YouTube Data API has not been used in project before or it is disabled"

**Cause**: The YouTube Data API v3 is not enabled in your Google Cloud project.

**Solution**:
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Select your project (or create a new one)
3. Follow Google's [YouTube Data API setup guide](https://developers.google.com/youtube/v3/getting-started) to enable the API
4. Wait 2-5 minutes for the API to be fully activated
5. Try your request again

### Error: "Access denied" or "Insufficient permissions"

Your OAuth scope or API key does not have the required permissions.

- For OAuth, call `yt_oauth()` with a token path that does not contain a usable
  token, or remove the cached token reported by `formals(yt_oauth())$token`.
- For API keys, confirm that the key's project has the YouTube Data API enabled.
- Private data and every write operation require OAuth.

## Authentication Issues

### Error: "Both app_id and app_secret are required"

**Complete Setup Instructions**:
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing one
3. Enable YouTube Data API v3
4. Go to [Credentials](https://console.cloud.google.com/apis/credentials)
5. Click "Create Credentials" > "OAuth client ID"
6. Choose "Desktop application"
7. Note the Client ID and Client Secret
8. Use: `yt_oauth("your_client_id", "your_client_secret")`

### OAuth browser issues

Google requires installed applications to use a system browser and local
redirect. Its former out-of-band copy-and-paste flow is no longer supported.

- Confirm that the OAuth client type is "Desktop app".
- Run the initial authorization in an interactive R session that can open a
  browser and receive a loopback redirect.
- Reuse the saved token for later non-interactive sessions.

## API Quota and Rate Limits

### Error: "Quota exceeded"

You have exhausted one of the project's daily quota buckets.

**Solutions**:
- Wait until quota resets at midnight Pacific Time.
- Inspect the project's actual usage in Google Cloud Console.
- Use batch operations and the response cache to avoid repeated requests.
- Request a quota increase if the application needs a higher allocation.

### Error: "Rate limit exceeded" (429)

**Cause**: Too many requests in a short time period.

**Solution**: Add delays between requests:
```r
# Add small delays between requests
Sys.sleep(0.1)  # 100ms delay
```

## Common Function Issues

### download_caption() returns 403

Caption download requires OAuth and permission to access the caption track.

Authenticate as the channel that owns the video or as an authorized content
partner.

### Comments functions return fewer results than expected

**Cause**: YouTube API has built-in limits and some comments may be hidden.

**Solutions**:
- YouTube limits total searchable results (~500 for search, varies for comments)
- Some comments may be filtered by YouTube's spam detection
- Private or deleted comments won't appear in results

### Channel lookup fails

**Cause**: Channel usernames may have changed to custom URLs.

**Solution**: Use channel IDs instead of usernames when possible:
```r
# Instead of username
get_channel_details(channel_ids = "UC_x5XG1OV2P6uZZ5FSM9Ttw")
get_channel_details(usernames = "oldusername")
```

## Performance Tips

1. **Use batch operations** for multiple videos/channels
2. **Cache API responses** for repeated analysis
3. **Use appropriate parts** - only request data you need
4. **Implement retry logic** for transient failures
5. **Monitor quota usage** with built-in tracking functions

## Getting Help

Open an issue at <https://github.com/gojiplus/tuber/issues> with the function
call, the error class and message, and `sessionInfo()`. Remove API keys, OAuth
tokens, and other credentials before posting.
3. Test with simple examples before complex operations
4. Check the [GitHub issues](https://github.com/gojiplus/tuber/issues) for similar problems
5. When reporting issues, include:
   - Complete error messages
   - Minimal reproducible example
   - Your Google Cloud project setup details (without sharing credentials)