Error: Invalid API Version... Come Again?

One thing that I love about Salesforce is the sneak peak that we get in our sandboxes prior to each new release. On occasion though, I've worked on something new in one of these developer preview sandboxes and wanted to deploy my code to production. Only to receive an "Invalid API Version" error message.

Right now, my production environment is Summer '11, but my sandbox is Winter '12. If I were to create a new Visualforce page in my production environment, the Salesforce API version would be version 22.0. If I do the same within my sandbox, the API version is 23.0. The dilemma, upon deployment, is trying to push version 23.0 into a platform that only supports up to version 22.0; hence the "Invalid API Version" error message. I've done this with pages, but I imagine it is quite possible to experience with classes, triggers, templates, etc.

How do you fix this? Wait for the update to be applied to your production environment. Just kidding...
Within Salesforce, you can go to "Setup" --> "Develop" --> "Pages" --> and click on your page's name. From there click on the "Edit" button and then on the "Version Settings" tab. Drop your version down to that which matches your production instance. Click on "Save" and try your deployment again.
From within the Force.com IDE/Eclipse, expand your project and browse to the page, class, trigger, whatever file you're having issues deploying. Below that file, you should see an identically named file, appended with -meta.xml... edit that. In the editor pane, you should see an xml file structure. You may need to click on the "Source" tab below. Look for the tags and replace the version number with that which matches your production instance. Save it down and try deployment again.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<ApexPage xmlns="http://soap.sforce.com/2006/04/metadata">
  
<apiVersion>23.0</apiVersion> 
    <description>Default Force.com Change Password page</description>
    <label>ChangePassword</label>
</ApexPage>

While that should fix your problem, keep in mind you are reducing the API version, some it is possible that if you are utilizing some of the new release's features - your file won't save after the API version number change and those features won't work.

Speaking of version numbers, one question you might have is whether or not you need to go through all of your old code to update the API Version after a new update comes along. Once Winter '12 comes out, am I going to update all of my classes, triggers, and pages to be version 23.0? No - you don't have to and you can leave them as is as Salesforce will maintain backwards compatibility. If you want to use some nifty new tags or features that didn't exist in that version set, you might have to change it down the road - but you'll know when you have to.