Troubleshooting - Historia Diaria

Common Issues and Solutions

API Connection Failures

Symptom

Your generated story shows “Error” as the title or “Fallo al conectar con la API” as the content.

Error Handling in Code

The script includes basic error handling:

try:
    response = requests.post(
        url="https://openrouter.ai/api/v1/chat/completions",
        headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
        data=json.dumps({"model": "stepfun/step-3.5-flash:free", "messages": [{"role": "user", "content": prompt}]})
    )
    respuesta_ia = response.json()['choices'][0]['message']['content']
except Exception as e:
    respuesta_ia = "<TITULO>Error</TITULO><HISTORIA>Fallo al conectar con la API.</HISTORIA><IMAGEN>error</IMAGEN>"

Possible Causes and Solutions

Missing or Invalid API Key - This is the most common cause of connection failures.

Solution:

Verify your API key is correctly set in GitHub Secrets
Go to your repository → Settings → Secrets and variables → Actions
Check that OPENROUTER_API_KEY exists and contains a valid key
Get a new API key from OpenRouter if needed

Network Issues:

Check OpenRouter status page for API outages
GitHub Actions may have temporary network issues - wait and retry

API Rate Limits:

Free tier models have usage limits
Check your OpenRouter dashboard for quota information
Consider upgrading or using a different model

Invalid Response Format:

# The code expects this structure:
response.json()['choices'][0]['message']['content']

If the API returns an error object instead, this will fail.

To debug API responses, you can temporarily add print(response.text) after line 24 in generar_historia.py to see the raw response in GitHub Actions logs.

GitHub Actions Not Running

Symptom

The workflow doesn’t execute automatically at the scheduled time.

Scheduled Execution Details

The workflow is configured to run daily:

on:
  schedule:
    # Los servidores usan la hora universal (UTC).
    # Las 13:00 UTC equivalen exactamente a las 8:00 AM en Lima.
    - cron: '0 13 * * *'
  workflow_dispatch:

Common Causes

1. Repository Inactivity

GitHub automatically disables scheduled workflows in repositories with no activity for 60 days.

Solution:

Make any commit to the repository
Or manually trigger the workflow using the “Actions” tab
GitHub will send you an email warning before disabling

2. Workflow Disabled Manually Solution:

Go to the “Actions” tab in your repository
Click on “Actualizar Historia Diaria” workflow
If you see “This workflow was disabled”, click “Enable workflow”

3. Incorrect Cron Syntax The current cron schedule:

0 13 * * * = Every day at 13:00 UTC (8:00 AM Lima time)

4. GitHub Actions Delays

Scheduled workflows may be delayed by up to 10-15 minutes during high-load periods on GitHub’s infrastructure. This is normal behavior.

Secret Configuration Errors

Symptom

Workflow fails with authentication errors or the API key appears empty.

How Secrets Work

The workflow accesses the secret like this:

- name: 4. Ejecutar tu script
  env:
    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
  run: python generar_historia.py

And the Python script reads it:

api_key = os.environ.get("OPENROUTER_API_KEY")

Common Mistakes

Secret Name Mismatch:

Secret must be named exactly OPENROUTER_API_KEY
Secret names are case-sensitive

Wrong Scope:

Secrets must be set in Repository Settings, not Environment secrets
Path: Settings → Secrets and variables → Actions → Repository secrets

Leading/Trailing Spaces:

Copy the API key carefully without extra spaces
GitHub Secrets trim spaces, but verify the key is correct

Validation: Check the workflow logs:

# The log should show:
Run python generar_historia.py

If you see errors about missing authorization, the secret isn’t being passed correctly.

File Permission Issues

Symptom

Workflow fails with “Permission denied” or “failed to push some refs”.

Required Permissions

The workflow needs write access:

permissions:
  contents: write  # Le damos permiso a la máquina para modificar tu repositorio

Solutions

1. Enable Workflow Permissions

Go to Settings → Actions → General
Scroll to “Workflow permissions”
Select “Read and write permissions”
Check “Allow GitHub Actions to create and approve pull requests” (optional)
Click “Save”

2. Branch Protection Rules If you have branch protection enabled on main:

Workflows may not be able to push directly
Either disable branch protection or allow Actions to bypass

Do not modify the git configuration in the workflow. The current setup is correct:

git config --local user.email "github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"

Invalid API Responses

Symptom

Stories are generated but titles or content are missing or malformed.

Response Parsing Logic

The script uses regex to extract content:

titulo_match = re.search(r'<TITULO>(.*?)</TITULO>', respuesta_ia, re.DOTALL)
historia_match = re.search(r'<HISTORIA>(.*?)</HISTORIA>', respuesta_ia, re.DOTALL)

nuevo_titulo = titulo_match.group(1).strip() if titulo_match else "Historia sin título"
nueva_historia = historia_match.group(1).strip() if historia_match else "Error al generar la historia."

Common Issues

AI Doesn’t Follow Format: The AI model sometimes ignores the prompt format. Fallback Values:

If <TITULO> tags not found: “Historia sin título”
If <HISTORIA> tags not found: “Error al generar la historia.”

Solutions:

Try a different model - Edit line 23 in generar_historia.py:

# Current model:
"model": "stepfun/step-3.5-flash:free"

# Alternative free models:
"model": "google/gemini-flash-1.5"
"model": "meta-llama/llama-3-8b-instruct:free"

Strengthen the prompt - The prompt at lines 11-17 can be made more explicit

Add validation logging - Temporarily add debugging:

print(f"Raw response: {respuesta_ia}")
print(f"Title match: {titulo_match}")
print(f"Story match: {historia_match}")

History JSON Corruption

Symptom

The sidebar menu doesn’t appear or shows broken links.

How History Works

The script maintains historial.json:

if os.path.exists('historial.json'):
    with open('historial.json', 'r', encoding='utf-8') as f:
        historial = json.load(f)
else:
    historial = {}

Expected JSON Format

{
  "Marzo 2026": [
    {
      "titulo": "La Última Frontera",
      "archivo": "historia-2026-03-05.html"
    }
  ]
}

Fixing Corruption

If historial.json contains invalid JSON syntax, the script will crash.

Solution 1: Manual Fix

Open historial.json in your repository
Click “Edit”
Fix JSON syntax errors (use a JSON validator)
Commit changes

Solution 2: Reset History

Delete historial.json from your repository
The script will create a fresh one on next run
Previous stories will still exist as HTML files
You’ll need to manually rebuild the history or let it accumulate

Prevention:

Don’t manually edit historial.json unless you’re comfortable with JSON
Use a JSON validator before committing changes

Template Rendering Errors

Symptom

Generated HTML pages show placeholders like {{TITULO}} instead of actual content.

Template Variables

The script replaces these placeholders in plantilla.html:

contenido_html = contenido_html.replace('{{TITULO}}', nuevo_titulo)
contenido_html = contenido_html.replace('{{HISTORIA}}', nueva_historia)
contenido_html = contenido_html.replace('{{IMAGEN_URL}}', url_imagen)
contenido_html = contenido_html.replace('{{MENU}}', menu_html)

Common Causes

Missing plantilla.html:

The template file must exist in the repository root
Check line 85: with open('plantilla.html', 'r', encoding='utf-8') as archivo:

Solution: Ensure plantilla.html exists and contains:

{{TITULO}} - Story title
{{HISTORIA}} - Story content
{{IMAGEN_URL}} - Image URL
{{MENU}} - Sidebar menu HTML

Variable Name Typos: Make sure placeholders match exactly (case-sensitive). Encoding Issues: The script uses UTF-8 encoding. If your template has different encoding:

with open('plantilla.html', 'r', encoding='utf-8') as archivo:

Dependency Installation Failures

Symptom

Workflow fails at the “Instalar dependencias” step.

Installation Steps

- name: 3. Instalar dependencias (NUEVO PASO)
  run: |
    python -m pip install --upgrade pip
    pip install requests

Solutions

Network Timeouts:

Retry the workflow (usually temporary)
GitHub Actions has reliable PyPI connectivity

Python Version Issues: The workflow uses Python 3.10:

- name: 2. Preparar e instalar Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.10'

If needed, you can change to '3.11' or '3.12'. Additional Dependencies: The script only requires:

requests (for API calls)
json, re, datetime, uuid, os (all built-in)

Debugging Tips

Viewing Workflow Logs

Go to your repository on GitHub
Click the “Actions” tab
Click on a workflow run (green check, red X, or yellow dot)
Click on the job name “generar-pagina”
Expand each step to see detailed output

Testing Locally

You can test the script on your computer:

# Set environment variable
export OPENROUTER_API_KEY="your-api-key-here"

# Install dependencies
pip install requests

# Run the script
python generar_historia.py

Local testing requires plantilla.html in the same directory.

Manual Workflow Trigger

Test without waiting for the schedule:

Go to Actions tab
Click “Actualizar Historia Diaria”
Click “Run workflow” button
Select branch (usually main)
Click “Run workflow”

Getting Help

If you’re still experiencing issues:

Check workflow logs for specific error messages
Verify all secrets are correctly configured
Test the API key separately using curl or Postman
Review recent commits that might have introduced changes
Check GitHub Status at githubstatus.com

Most issues are related to API keys or GitHub Actions permissions. Double-check these first!

Get Started

Core Concepts

Configuration

Reference

Help

​Common Issues and Solutions

​API Connection Failures

​Symptom

​Error Handling in Code

​Possible Causes and Solutions

​GitHub Actions Not Running

​Symptom

​Scheduled Execution Details

​Common Causes

​Secret Configuration Errors

​Symptom

​How Secrets Work

​Common Mistakes

​File Permission Issues

​Symptom

​Required Permissions

​Solutions

​Invalid API Responses

​Symptom

​Response Parsing Logic

​Common Issues

​History JSON Corruption

​Symptom

​How History Works

​Expected JSON Format

​Fixing Corruption

​Template Rendering Errors

​Symptom

​Template Variables

​Common Causes

​Dependency Installation Failures

​Symptom

​Installation Steps

​Solutions

​Debugging Tips

​Viewing Workflow Logs

​Testing Locally

​Manual Workflow Trigger

​Getting Help

Build docs developers (and LLMs) love

Common Issues and Solutions

API Connection Failures

Symptom

Error Handling in Code

Possible Causes and Solutions

GitHub Actions Not Running

Symptom

Scheduled Execution Details

Common Causes

Secret Configuration Errors

Symptom

How Secrets Work

Common Mistakes

File Permission Issues

Symptom

Required Permissions

Solutions

Invalid API Responses

Symptom

Response Parsing Logic

Common Issues

History JSON Corruption

Symptom

How History Works

Expected JSON Format

Fixing Corruption

Template Rendering Errors

Symptom

Template Variables

Common Causes

Dependency Installation Failures

Symptom

Installation Steps

Solutions

Debugging Tips

Viewing Workflow Logs

Testing Locally

Manual Workflow Trigger

Getting Help