IV. Reference

Troubleshooting

Overview

This page outlines common issues and solutions for the Gracenote Video MCP Server.

Authentication Issues

Cannot Authenticate / NotAuthorizedException

Symptoms:

• Login fails with "NotAuthorizedException"
• "Invalid username or password" error

Solutions:

1. Verify your Cognito credentials are correct
2. Check username and password for typos
3. Ensure client ID and client secret are correct
4. Confirm your account has been activated by Gracenote
5. Contact your Gracenote representative if credentials are lost

Code Example:

Code
 
try:
    token = get_cognito_id_token(...)
except ClientError as e:
    if e.response['Error']['Code'] == 'NotAuthorizedException':
        print("Invalid credentials - check username/password")

Token Expired / 401 Unauthorized

Symptoms:

• "401 Unauthorized" error
• "Token expired" message
• Authentication works initially but fails after 1 hour

Solutions:

1. Tokens expire after 1 hour - implement token refresh
2. Get a new token before making requests
3. Implement automatic token refresh for long-running processes

Code Example:

The GracenoteClient from mcp_utils.py handles token refresh automatically. If building a custom client, implement refresh like this:

Code
 
import time

class TokenRefreshMixin:
    def __init__(self):
        self.token_acquired_at = None
        self.token_expires_in = 3600  # 1 hour
    
    def _should_refresh_token(self) -> bool:
        if not self.token_acquired_at:
            return True
        elapsed = time.time() - self.token_acquired_at
        return elapsed > (self.token_expires_in - 300)  # 5 min buffer
    
    async def ensure_valid_token(self):
        if self._should_refresh_token():
            token = self._get_token()
            self.headers["Authorization"] = f"Bearer {token}"
            self.token_acquired_at = time.time()

UserNotConfirmedException

Symptoms:

• "User not confirmed" error
• Cannot log in despite having credentials

Solutions:

1. Contact Gracenote to confirm your user account
2. Verify onboarding process is complete
3. Check with your Gracenote representative

Connection Issues

Connection Timeout

Symptoms:

• Connection times out
• Cannot reach MCP Server
• Network errors

Solutions:

1. Verify MCP_SERVER_HOST is correct
2. Verify MCP_SERVER_PORT is correct (typically 443)
3. Check network connectivity
4. Ensure firewall allows HTTPS traffic on port 443
5. Test with curl or similar tool:

   Code
    
   curl -I https://your-mcp-server:443

SSL/TLS Errors

Symptoms:

• SSL certificate errors
• TLS handshake failures

Solutions:

1. Ensure you're using HTTPS (not HTTP) for port 443
2. Update SSL certificates on your system
3. Check system time is correct (affects certificate validation)
4. Contact support if certificate issues persist

Query Issues

No Results Returned

Symptoms:

• LLM queries return empty results
• "No matches found" for valid titles

Solutions:

1. Verify content type is supported (movies, series, episodes only)
2. Check language and country codes are correct
3. Try with fewer search parameters
4. Check for typos in title names
5. Verify content is available in the specified country

Example:

Code
 
Bad:  language="eng", country="US"
Good: language="en", countryCode="USA"

Unexpected Results

Symptoms:

• Wrong titles returned
• Low confidence matches
• Irrelevant results

Solutions:

1. Encourage users to provide more specific information (year, cast, genre) in their queries
2. Check language/country codes match your intent
3. Review query for ambiguity
4. Try alternate title spellings

Note: Your LLM automatically extracts parameters from user queries. More specific user input leads to better results.

Performance Issues

Slow Response Times

Symptoms:

• Queries take longer than expected
• Timeouts on complex queries

Solutions:

1. Check network latency to MCP Server
2. Simplify queries where possible
3. Monitor usage in Customer Console
4. Contact support if consistent slow performance

Data Issues

Missing Images

Symptoms:

• Image URLs return 404
• Images not loading

Solutions:

1. Verify MediaCloud subdomain is correct
2. Check image URL format
3. Ensure image hasn't expired
4. Remember: Image URLs are demo only - cache locally for production

Incorrect Availability Data

Symptoms:

• Availability doesn't match expectations
• Missing streaming services

Solutions:

1. Remember: Availability is "today" only (current availability)
2. Check country code is correct
3. Verify streaming service is not an entitled catalog
4. Note: Linear TV and FAST channels are excluded

Wrong Language Version

Symptoms:

• Getting wrong language metadata
• Unexpected language in results

Solutions:

1. Verify language parameter is correct
2. Check if using general language (matches all variants) vs. locale-specific
3. Use locale-specific tags for exact matching (e.g., "pt-BR" for Brazilian Portuguese, not just "pt")

Console Issues

Cannot Access Customer Console

Symptoms:

• Cannot log in to console
• Console URL not working

Solutions:

1. Verify console URL with Gracenote representative
2. Check login credentials
3. Clear browser cache and cookies
4. Try different browser
5. Contact support for access issues

Data Not Appearing in Console

Symptoms:

• Usage data missing
• Billing information not showing

Solutions:

1. Check data currency (near-real time, may have slight delay)
2. Verify date range filters
3. Refresh browser
4. Wait a few minutes for data to sync
5. Contact support if data is consistently missing

Integration Issues

LLM Not Calling Tools

Symptoms:

• LLM not using MCP tools
• Queries not grounded with Gracenote data

Solutions:

1. Verify MCP client is properly connected
2. Check System Prompt configuration
3. Ensure LLM has access to tool descriptions
4. Review Architecture
5. Test with Demo to verify server is working

Tool Call Errors

Symptoms:

• "Invalid input" errors
• "Maximum count exceeded" errors

Solutions:

1. Review error message for specific guidance
2. Verify the MCP Server is receiving properly formatted requests
3. Check for count limit violations (e.g., max 3 cast members)
4. Ensure required parameters are provided
5. Your LLM should self-correct based on error messages

Note: Your LLM handles parameter formatting automatically. These errors typically indicate the LLM needs adjustment in its system prompt or the user query needs clarification.

Getting Help

Before Contacting Support

1. Check this troubleshooting guide
2. Review relevant documentation pages
3. Export usage/call data if applicable
4. Note error messages and timestamps
5. Try to reproduce the issue

How to Contact Support

Contact your assigned account manager, and include the following information:

• ClientId
• Timestamp of issue
• Error messages (exact text)
• Steps to reproduce
• Expected vs. actual behavior
• Call details (if applicable)
• Screenshots (if relevant)