Cause: Syntax error in the spec file.

Solutions:

• Check for missing colons, commas, or quotes
• Verify indentation (YAML is whitespace-sensitive)
• Use a YAML/JSON validator to find the exact line
• For YAML: tabs are NOT allowed, use spaces only

Cause: File is valid YAML/JSON but not an OpenAPI spec.

Solutions:

• Ensure the file has openapi: "3.x.x" or swagger: "2.0"
• Check that info and paths are present
• Verify you're importing the right file (not a config or schema file)

Possible causes:

• CORS blocked - Server doesn't allow cross-origin requests
• Auth required - URL needs authentication
• Wrong URL - 404 or redirect to HTML page
• Network error - Firewall or DNS issue

Solutions:

• Download the file manually and use "Upload File" instead
• Check if the URL returns JSON/YAML (not an HTML page)
• Try accessing the URL directly in your browser first

Cause: Very large specs (1000+ endpoints) require more processing.

Tips:

• Wait for import to complete - don't close the window
• Consider splitting into multiple specs if possible
• Use external $ref files to modularize large specs

Cause: Every operation MUST have a responses object.

Cause: Tigrister limits external $ref resolution to 10 levels deep.

Solutions:

• Flatten deeply nested external references
• Use internal refs (#/components/...) where possible
• Consolidate shared schemas into fewer files

Cause: Self-referential schemas (A → B → A) are detected and stopped.

Behavior: Circular refs return {} to prevent infinite loops.

Impact:

• Example generation shows "..." for circular parts
• Schema validation still works correctly
• This is expected behavior, not an error

Cause: Reference points to a non-existent schema.

Solutions:

• Check the schema name spelling (case-sensitive!)
• Ensure the referenced schema exists in components/schemas
• Verify the path format: #/components/schemas/Name

Cause: Each operation must have a unique operationId.

Solution: Rename one of the duplicate IDs.

Cause: Schema type must be one of the allowed values.

Valid types:

Possible causes:

• Token expired - re-authorize with fresh credentials
• Wrong credentials - double-check API key or password
• Missing scopes - endpoint requires scopes you didn't request
• Wrong auth scheme - using API key when OAuth2 is expected

Steps to fix:

1. Click "Authorize" button
2. Log out of current session
3. Re-enter credentials
4. Verify the lock icon turns solid (authorized)

Cause: Auth is valid but you lack permission for this resource.

Solutions:

• Check if the endpoint requires admin/elevated permissions
• Verify your user has access to the resource ID
• For OAuth2: ensure you requested the required scopes

Cause: OAuth provider can't redirect back to Tigrister.

Solutions:

• Check that the OAuth app allows localhost/desktop redirects
• Verify authorizationUrl is correct in the spec
• Try with a different browser if popups are blocked

Causes & solutions:

• Lock icon is open - Click Authorize and enter credentials
• Wrong scheme authorized - Check which scheme the endpoint requires
• security: [] on endpoint - Endpoint is public, no auth sent intentionally

Good news: OAuth2 tokens are automatically refreshed before they expire!

How it works:

• Tigrister checks token expiration before each request
• If token is about to expire, refresh happens automatically
• You don't need to manually re-authorize during long sessions

If refresh fails:

• Click Authorize and log out
• Re-authorize with fresh credentials
• Check if refresh_token scope was granted

Cause: You need to save before changes sync.

Solution:

1. Click the "Save" button or press Cmd/Ctrl + S
2. If Save is disabled, check for validation errors
3. Fix any red error markers before saving

Cause: There are validation errors in the spec.

Solution:

• Check the error count in the toolbar
• Look for red underlines in the Code Editor
• Hover over errors to see details
• Fix all errors - then Save becomes enabled

Prevention:

• Look for the amber dot next to project name (indicates unsaved changes)
• Save frequently while editing
• Don't close the window if you see "Unsaved changes" warning

Recovery:

• Check browser history if you copied spec content recently
• If you clicked "Restore", the last saved version is loaded
• Unfortunately, unsaved changes cannot be recovered after closing

Cause: Editor and Visual Designer can be out of sync during editing.

Solutions:

• Toggle to Editor mode and back to refresh
• Save the spec to sync all views
• Close and re-open the Designer if issues persist

Cause: Browser blocks cross-origin requests from embedded preview.

Solutions:

• Use Area Mode instead - it bypasses browser CORS restrictions
• Configure your API server to allow CORS from Tigrister
• For local development, use a CORS proxy

Causes:

• Server is not running
• Wrong port number in server URL
• Firewall blocking the connection
• Server only listening on localhost but you're using a different hostname

Solution: Verify the server URL matches a running service.

Causes:

• Self-signed certificate on development server
• Expired certificate
• Certificate hostname mismatch

Solutions:

• For development: use http:// instead of https://
• Trust the certificate in your system settings
• For production: fix the certificate issue on the server

Cause: Server doesn't accept the Content-Type you're sending.

Solutions:

• Check what Content-Type the endpoint accepts (look at requestBody)
• Ensure you're using the right body type (JSON vs form-data)
• Verify the Content-Type header matches the body format

Cause: Server expects different array format than what's being sent.

Solutions:

• Check the parameter's style setting (form, spaceDelimited, etc.)
• Verify the explode setting matches server expectations
• Test different formats: ?ids=1,2,3 vs ?ids=1&ids=2&ids=3

Symptom: {{VAR}} appears literally in the request instead of the value.

Causes & solutions:

• Variable not defined - Add it to your active environment
• Wrong environment selected - Check the environment dropdown
• Typo in variable name - Names are case-sensitive
• Single braces - Use {{var}} not {var}